[portal-commits] JBoss Portal SVN: r12289 - in docs/enterprise/trunk/Reference_Guide: en-US and 3 other directories.

Author: skittoli(a)redhat.com Date: 2008-11-12 18:51:15 -0500 (Wed, 12 Nov 2008) New Revision: 12289 Modified: docs/enterprise/trunk/Reference_Guide/en-US/resolved.xml docs/enterprise/trunk/Reference_Guide/pom.xml docs/enterprise/trunk/Reference_Guide/tmp/en-US/xml/Book_Info.xml docs/enterprise/trunk/Reference_Guide/tmp/en-US/xml/Common_Content/Feedback.xml docs/enterprise/trunk/Reference_Guide/tmp/en-US/xml/Common_Content/Legal_Notice.xml docs/enterprise/trunk/Reference_Guide/tmp/en-US/xml_tmp/Book_Info.xml Log: updates Modified: docs/enterprise/trunk/Reference_Guide/en-US/resolved.xml =================================================================== --- docs/enterprise/trunk/Reference_Guide/en-US/resolved.xml 2008-11-12 22:44:10 UTC (rev 12288) +++ docs/enterprise/trunk/Reference_Guide/en-US/resolved.xml 2008-11-12 23:51:15 UTC (rev 12289) @@ -0,0 +1,17450 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd" [ +<!ENTITY uArr "⇑"> +<!ENTITY hcirc "ĥ"> +<!ENTITY icirc "î"> +<!ENTITY equals "="> +<!ENTITY cong "≅"> +<!ENTITY icy "и"> +<!ENTITY HARDcy "Ъ"> +<!ENTITY Ecaron "Ě"> +<!ENTITY clubs "♣"> +<!ENTITY phmmat "ℳ"> +<!ENTITY sqcap "⊓"> +<!ENTITY thorn "þ"> +<!ENTITY Lcedil "Ļ"> +<!ENTITY verbar "|"> +<!ENTITY rarr "→"> +<!ENTITY cire "≗"> +<!ENTITY DZcy "Џ"> +<!ENTITY b.delta "δ"> +<!ENTITY Gcirc "Ĝ"> +<!ENTITY ocir "⊚"> +<!ENTITY circ "^"> +<!ENTITY Igr "Ι"> +<!ENTITY udigr "ϋ"> +<!ENTITY prime "′"> +<!ENTITY npr "⊀"> +<!ENTITY b.pi "π"> +<!ENTITY frac58 "⅝"> +<!ENTITY ldquor "„"> +<!ENTITY sqsup "⊐"> +<!ENTITY boxDR "╒"> +<!ENTITY kcedil "ķ"> +<!ENTITY vDash "⊨"> +<!ENTITY Scedil "Ş"> +<!ENTITY perp "⊥"> +<!ENTITY b.Gamma "Γ"> +<!ENTITY b.kappa "κ"> +<!ENTITY Uuml "Ü"> +<!ENTITY mnplus "∓"> +<!ENTITY nearr "↗"> +<!ENTITY nrtri "⋫"> +<!ENTITY cupre "≼"> +<!ENTITY boxV "║"> +<!ENTITY Zdot "Ż"> +<!ENTITY pound "£"> +<!ENTITY lharu "↼"> +<!ENTITY boxdr "┌"> +<!ENTITY ocy "о"> +<!ENTITY xgr "ξ"> +<!ENTITY b.xi "ξ"> +<!ENTITY middot "·"> +<!ENTITY larr "←"> +<!ENTITY xrArr "⇒"> +<!ENTITY Ncy "Н"> +<!ENTITY acute "´"> +<!ENTITY phis "φ"> +<!ENTITY ncedil "ņ"> +<!ENTITY lAarr "⇚"> +<!ENTITY sqsube "⊑"> +<!ENTITY quot '"'> +<!ENTITY TSHcy "Ћ"> +<!ENTITY amacr "ā"> +<!ENTITY otimes "⊗"> +<!ENTITY inodot "ı"> +<!ENTITY gsdot "⋗"> +<!ENTITY LJcy "Љ"> +<!ENTITY phiv "ϕ"> +<!ENTITY odblac "ő"> +<!ENTITY filig "fi"> +<!ENTITY amalg "∐"> +<!ENTITY sdotb "⊡"> +<!ENTITY boxDL "╕"> +<!ENTITY Theta "Θ"> +<!ENTITY cdot "ċ"> +<!ENTITY ordm "º"> +<!ENTITY atilde "ã"> +<!ENTITY squf "▪"> +<!ENTITY notin "∉"> +<!ENTITY nmid "∤"> +<!ENTITY shchcy "щ"> +<!ENTITY lfloor "⌊"> +<!ENTITY Xi "Ξ"> +<!ENTITY Hstrok "Ħ"> +<!ENTITY period "."> +<!ENTITY numsp " "> +<!ENTITY nldr "‥"> +<!ENTITY boxdl "┐"> +<!ENTITY Fcy "Ф"> +<!ENTITY tscy "ц"> +<!ENTITY Iukcy "І"> +<!ENTITY cross "✗"> +<!ENTITY ohgr "ω"> +<!ENTITY nbsp " "> +<!ENTITY ni "∍"> +<!ENTITY comp "∁"> +<!ENTITY boxH "═"> +<!ENTITY b.Delta "Δ"> +<!ENTITY Oslash "Ø"> +<!ENTITY ndash "–"> +<!ENTITY marker "▮"> +<!ENTITY ordf "ª"> +<!ENTITY nsce "⋡"> +<!ENTITY vrtri "⊳"> +<!ENTITY ubrcy "ў"> +<!ENTITY Ccirc "Ĉ"> +<!ENTITY quest "?"> +<!ENTITY ne "≠"> +<!ENTITY gap "≳"> +<!ENTITY efDot "≒"> +<!ENTITY rcy "р"> +<!ENTITY bsim "∽"> +<!ENTITY bgr "β"> +<!ENTITY omacr "ō"> +<!ENTITY umacr "ū"> +<!ENTITY lpar "("> +<!ENTITY uharl "↿"> +<!ENTITY Gcy "Г"> +<!ENTITY ast "*"> +<!ENTITY acy "а"> +<!ENTITY thetas "θ"> +<!ENTITY uring "ů"> +<!ENTITY Zcaron "Ž"> +<!ENTITY horbar "―"> +<!ENTITY star "⋆"> +<!ENTITY timesb "⊠"> +<!ENTITY npre "⋠"> +<!ENTITY real "ℜ"> +<!ENTITY nrArr "⇏"> +<!ENTITY dlarr "↙"> +<!ENTITY oplus "⊕"> +<!ENTITY Xgr "Ξ"> +<!ENTITY ucy "у"> +<!ENTITY thetav "ϑ"> +<!ENTITY jcirc "ĵ"> +<!ENTITY uharr "↾"> +<!ENTITY mgr "μ"> +<!ENTITY hearts "♥"> +<!ENTITY nvDash "⊭"> +<!ENTITY yicy "ї"> +<!ENTITY dot "˙"> +<!ENTITY alpha "α"> +<!ENTITY wedgeq "≙"> +<!ENTITY bowtie "⋈"> +<!ENTITY boxDr "╓"> +<!ENTITY b.upsi "υ"> +<!ENTITY euml "ë"> +<!ENTITY vArr "⇕"> +<!ENTITY lgr "λ"> +<!ENTITY b.rhov "ϱ"> +<!ENTITY ubreve "ŭ"> +<!ENTITY copysr "℗"> +<!ENTITY cap "∩"> +<!ENTITY aogon "ą"> +<!ENTITY racute "ŕ"> +<!ENTITY rthree "⋌"> +<!ENTITY Sgr "Σ"> +<!ENTITY uacute "ú"> +<!ENTITY Tcaron "Ť"> +<!ENTITY dagger "†"> +<!ENTITY oast "⊛"> +<!ENTITY prnE ""> +<!ENTITY thkap "≈"> +<!ENTITY boxdR "╔"> +<!ENTITY dgr "δ"> +<!ENTITY nacute "ń"> +<!ENTITY hardcy "ъ"> +<!ENTITY sqsupe "⊒"> +<!ENTITY TScy "Ц"> +<!ENTITY reg "®"> +<!ENTITY cir "○"> +<!ENTITY lsquor "‚"> +<!ENTITY ycy "ы"> +<!ENTITY Sigma "Σ"> +<!ENTITY Gbreve "Ğ"> +<!ENTITY order "ℴ"> +<!ENTITY nlarr "↚"> +<!ENTITY eng "ŋ"> +<!ENTITY sacute "ś"> +<!ENTITY ensp " "> +<!ENTITY rarr2 "⇉"> +<!ENTITY coprod "∐"> +<!ENTITY iacgr "ί"> +<!ENTITY b.piv "ϖ"> +<!ENTITY rlhar2 "⇌"> +<!ENTITY boxDl "╗"> +<!ENTITY Pcy "П"> +<!ENTITY Dagger "‡"> +<!ENTITY khcy "х"> +<!ENTITY sigma "σ"> +<!ENTITY nltrie "⋬"> +<!ENTITY gjcy "ѓ"> +<!ENTITY b.alpha "α"> +<!ENTITY plusmn "±"> +<!ENTITY scnap "⋩"> +<!ENTITY vprime "′"> +<!ENTITY iota "ι"> +<!ENTITY Dcaron "Ď"> +<!ENTITY emsp " "> +<!ENTITY trie "≜"> +<!ENTITY boxdL "╖"> +<!ENTITY cacute "ć"> +<!ENTITY rcedil "ŗ"> +<!ENTITY lhblk "▄"> +<!ENTITY lnsim "⋦"> +<!ENTITY bsime "⋍"> +<!ENTITY Vvdash "⊪"> +<!ENTITY zgr "ζ"> +<!ENTITY Ncaron "Ň"> +<!ENTITY rcaron "ř"> +<!ENTITY radic "√"> +<!ENTITY colone "≔"> +<!ENTITY Ucy "У"> +<!ENTITY lcub "{"> +<!ENTITY mdash "—"> +<!ENTITY ogon "˛"> +<!ENTITY Lgr "Λ"> +<!ENTITY b.chi "χ"> +<!ENTITY Barwed "⌆"> +<!ENTITY odot "⊙"> +<!ENTITY softcy "ь"> +<!ENTITY yucy "ю"> +<!ENTITY Ogr "Ο"> +<!ENTITY ecirc "ê"> +<!ENTITY Uacute "Ú"> +<!ENTITY jcy "й"> +<!ENTITY Oacgr "Ό"> +<!ENTITY ntilde "ñ"> +<!ENTITY Uring "Ů"> +<!ENTITY Udigr "Ϋ"> +<!ENTITY squ "□"> +<!ENTITY image "ℑ"> +<!ENTITY Uacgr "Ύ"> +<!ENTITY uarr "↑"> +<!ENTITY sim "∼"> +<!ENTITY egr "ε"> +<!ENTITY aleph "ℵ"> +<!ENTITY nharr "↮"> +<!ENTITY kcy "к"> +<!ENTITY Rgr "Ρ"> +<!ENTITY ffilig "ffi"> +<!ENTITY boxvl "┤"> +<!ENTITY Iacgr "Ί"> +<!ENTITY ang90 "∟"> +<!ENTITY nrarr "↛"> +<!ENTITY nges "≱"> +<!ENTITY nsube "⊈"> +<!ENTITY nsup "⊅"> +<!ENTITY egs "⋝"> +<!ENTITY acirc "â"> +<!ENTITY Yuml "Ÿ"> +<!ENTITY ltrif "◂"> +<!ENTITY lagran "ℒ"> +<!ENTITY npar "∦"> +<!ENTITY scsim "≿"> +<!ENTITY boxvr "├"> +<!ENTITY Acirc "Â"> +<!ENTITY Ucirc "Û"> +<!ENTITY zcaron "ž"> +<!ENTITY shy "­"> +<!ENTITY ominus "⊖"> +<!ENTITY frac38 "⅜"> +<!ENTITY incare "℅"> +<!ENTITY uhblk "▀"> +<!ENTITY lEg "⋚"> +<!ENTITY gcy "г"> +<!ENTITY b.eta "η"> +<!ENTITY lnap ""> +<!ENTITY Iacute "Í"> +<!ENTITY yacute "ý"> +<!ENTITY dstrok "đ"> +<!ENTITY Imacr "Ī"> +<!ENTITY orarr "↻"> +<!ENTITY Eacgr "Έ"> +<!ENTITY apos "'"> +<!ENTITY b.epsiv "ε"> +<!ENTITY gcirc "ĝ"> +<!ENTITY udblac "ű"> +<!ENTITY planck "ℏ"> +<!ENTITY upsi "υ"> +<!ENTITY b.Lambda "Λ"> +<!ENTITY Bgr "Β"> +<!ENTITY scedil "ş"> +<!ENTITY Rarr "↠"> +<!ENTITY nrtrie "⋭"> +<!ENTITY nsub "⊄"> +<!ENTITY vcy "в"> +<!ENTITY b.epsis "ε"> +<!ENTITY Eacute "É"> +<!ENTITY boxvh "┼"> +<!ENTITY dcy "д"> +<!ENTITY Aring "Å"> +<!ENTITY Igrave "Ì"> +<!ENTITY utilde "ũ"> +<!ENTITY divonx "⋇"> +<!ENTITY lne "≨"> +<!ENTITY scnE ""> +<!ENTITY ccedil "ç"> +<!ENTITY supne "⊋"> +<!ENTITY empty "∅"> +<!ENTITY b.nu "ν"> +<!ENTITY top "⊤"> +<!ENTITY lcy "л"> +<!ENTITY b.gamma "γ"> +<!ENTITY aelig "æ"> +<!ENTITY iuml "ï"> +<!ENTITY Lcaron "Ľ"> +<!ENTITY bottom "⊥"> +<!ENTITY rarrhk "↪"> +<!ENTITY DScy "Ѕ"> +<!ENTITY idiagr "ΐ"> +<!ENTITY imacr "ī"> +<!ENTITY ltri "◃"> +<!ENTITY infin "∞"> +<!ENTITY le "≤"> +<!ENTITY sime "≃"> +<!ENTITY kappa "κ"> +<!ENTITY kappav "ϰ"> +<!ENTITY OElig "Œ"> +<!ENTITY urcrop "⌎"> +<!ENTITY darr2 "⇊"> +<!ENTITY lg "≶"> +<!ENTITY spar "∥"> +<!ENTITY Mgr "Μ"> +<!ENTITY rtri "▹"> +<!ENTITY daleth "ℸ"> +<!ENTITY sfrown "⌢"> +<!ENTITY epsiv "ε"> +<!ENTITY Omega "Ω"> +<!ENTITY colon ":"> +<!ENTITY prop "∝"> +<!ENTITY lArr "⇐"> +<!ENTITY Upsi "ϒ"> +<!ENTITY oslash "ø"> +<!ENTITY ap "≈"> +<!ENTITY Sup "⋑"> +<!ENTITY epsis "∊"> +<!ENTITY b.omega "ω"> +<!ENTITY rpar ")"> +<!ENTITY Abreve "Ă"> +<!ENTITY mldr "…"> +<!ENTITY ltrie "⊴"> +<!ENTITY Psi "Ψ"> +<!ENTITY Agrave "À"> +<!ENTITY Tcedil "Ţ"> +<!ENTITY auml "ä"> +<!ENTITY lcedil "ļ"> +<!ENTITY scirc "ŝ"> +<!ENTITY larrhk "↩"> +<!ENTITY varr "↕"> +<!ENTITY ncong "≇"> +<!ENTITY subE "⊆"> +<!ENTITY kjcy "ќ"> +<!ENTITY larr2 "⇇"> +<!ENTITY rsh "↱"> +<!ENTITY sdot "⋅"> +<!ENTITY wreath "≀"> +<!ENTITY cuepr "⋞"> +<!ENTITY frown "⌢"> +<!ENTITY Agr "Α"> +<!ENTITY uacgr "ύ"> +<!ENTITY rcub "}"> +<!ENTITY dharl "⇃"> +<!ENTITY bcy "б"> +<!ENTITY Tgr "Τ"> +<!ENTITY diam "⋄"> +<!ENTITY eacute "é"> +<!ENTITY xlArr "⇐"> +<!ENTITY leg "⋚"> +<!ENTITY boxvL "╡"> +<!ENTITY Kcy "К"> +<!ENTITY ncy "н"> +<!ENTITY sgr "σ"> +<!ENTITY beta "β"> +<!ENTITY exist "∃"> +<!ENTITY bprime "‵"> +<!ENTITY boxul "┘"> +<!ENTITY Zcy "З"> +<!ENTITY Iuml "Ï"> +<!ENTITY Scaron "Š"> +<!ENTITY sol "/"> +<!ENTITY boxvR "╞"> +<!ENTITY fcy "ф"> +<!ENTITY Egrave "È"> +<!ENTITY Utilde "Ũ"> +<!ENTITY lthree "⋋"> +<!ENTITY boxur "└"> +<!ENTITY dharr "⇂"> +<!ENTITY uarr2 "⇈"> +<!ENTITY lacute "ĺ"> +<!ENTITY spades "♠"> +<!ENTITY int "∫"> +<!ENTITY rect "▭"> +<!ENTITY compfn "∘"> +<!ENTITY b.sigma "σ"> +<!ENTITY Amacr "Ā"> +<!ENTITY prod "∏"> +<!ENTITY rpargt ""> +<!ENTITY b.sigmav "ς"> +<!ENTITY excl "!"> +<!ENTITY fnof "ƒ"> +<!ENTITY beth "ℶ"> +<!ENTITY yuml "ÿ"> +<!ENTITY rsquo "’"> +<!ENTITY pr "≺"> +<!ENTITY ccaron "č"> +<!ENTITY hyphen "-"> +<!ENTITY weierp "℘"> +<!ENTITY smile "⌣"> +<!ENTITY Egr "Ε"> +<!ENTITY eeacgr "ή"> +<!ENTITY nsc "⊁"> +<!ENTITY les "≤"> +<!ENTITY boxvH "╪"> +<!ENTITY KHcy "Х"> +<!ENTITY bernou "ℬ"> +<!ENTITY tgr "τ"> +<!ENTITY zacute "ź"> +<!ENTITY amp "&#38;"> +<!ENTITY lnE "≨"> +<!ENTITY nlE "≰"> +<!ENTITY sbsol "﹨"> +<!ENTITY Pi "Π"> +<!ENTITY b.beta "β"> +<!ENTITY b.mu "μ"> +<!ENTITY Ograve "Ò"> +<!ENTITY phone "☎"> +<!ENTITY iff "⇔"> +<!ENTITY gsim "≳"> +<!ENTITY rx "℞"> +<!ENTITY there4 "∴"> +<!ENTITY harrw "↭"> +<!ENTITY udiagr "ΰ"> +<!ENTITY otilde "õ"> +<!ENTITY DotDot "⃜"> +<!ENTITY lrhar2 "⇋"> +<!ENTITY lE "≦"> +<!ENTITY hstrok "ħ"> +<!ENTITY Racute "Ŕ"> +<!ENTITY rarrw "↝"> +<!ENTITY angmsd "∡"> +<!ENTITY tshcy "ћ"> +<!ENTITY szlig "ß"> +<!ENTITY nequiv "≢"> +<!ENTITY pcy "п"> +<!ENTITY darr "↓"> +<!ENTITY female "♀"> +<!ENTITY curarr "↷"> +<!ENTITY minusb "⊟"> +<!ENTITY aacute "á"> +<!ENTITY Dcy "Д"> +<!ENTITY THORN "Þ"> +<!ENTITY ucirc "û"> +<!ENTITY asymp "≍"> +<!ENTITY bcong "≌"> +<!ENTITY die "¨"> +<!ENTITY ograve "ò"> +<!ENTITY iexcl "¡"> +<!ENTITY frac56 "⅚"> +<!ENTITY rArr "⇒"> +<!ENTITY tprime "‴"> +<!ENTITY osol "⊘"> +<!ENTITY sqsub "⊏"> +<!ENTITY rho "ρ"> +<!ENTITY b.psi "ψ"> +<!ENTITY aring "å"> +<!ENTITY Edot "Ė"> +<!ENTITY lcaron "ľ"> +<!ENTITY rlarr2 "⇄"> +<!ENTITY EEacgr "Ή"> +<!ENTITY pi "π"> +<!ENTITY sect "§"> +<!ENTITY bepsi "∍"> +<!ENTITY ffllig "ffl"> +<!ENTITY lsh "↰"> +<!ENTITY dscy "ѕ"> +<!ENTITY macr "¯"> +<!ENTITY b.kappav "ϰ"> +<!ENTITY scaron "š"> +<!ENTITY dollar "$"> +<!ENTITY commat "@"> +<!ENTITY angsph "∢"> +<!ENTITY Udblac "Ű"> +<!ENTITY copy "©"> +<!ENTITY comma ","> +<!ENTITY diams "♦"> +<!ENTITY sube "⊆"> +<!ENTITY Dot "¨"> +<!ENTITY Cap "⋒"> +<!ENTITY nsmid ""> +<!ENTITY SOFTcy "Ь"> +<!ENTITY eegr "η"> +<!ENTITY lsim "≲"> +<!ENTITY ssmile "⌣"> +<!ENTITY nlt "≮"> +<!ENTITY boxHU "╨"> +<!ENTITY ZHcy "Ж"> +<!ENTITY abreve "ă"> +<!ENTITY lmidot "ŀ"> +<!ENTITY angst "Å"> +<!ENTITY b.lambda "λ"> +<!ENTITY uuml "ü"> +<!ENTITY IJlig "IJ"> +<!ENTITY ENG "Ŋ"> +<!ENTITY brvbar "¦"> +<!ENTITY esdot "≐"> +<!ENTITY boxuL "╝"> +<!ENTITY blk14 "░"> +<!ENTITY YAcy "Я"> +<!ENTITY caron "ˇ"> +<!ENTITY ohacgr "ώ"> +<!ENTITY sup3 "³"> +<!ENTITY flat "♭"> +<!ENTITY minus "−"> +<!ENTITY olarr "↺"> +<!ENTITY dlcorn "⌞"> +<!ENTITY boxuR "╙"> +<!ENTITY iukcy "і"> +<!ENTITY b.tau "τ"> +<!ENTITY Otilde "Õ"> +<!ENTITY ldquo "“"> +<!ENTITY lang "〈"> +<!ENTITY Verbar "‖"> +<!ENTITY ges "≥"> +<!ENTITY prap "≾"> +<!ENTITY thksim "∼"> +<!ENTITY Vcy "В"> +<!ENTITY yacy "я"> +<!ENTITY drcrop "⌌"> +<!ENTITY omega "ω"> +<!ENTITY Hcirc "Ĥ"> +<!ENTITY tstrok "ŧ"> +<!ENTITY ang "∠"> +<!ENTITY khgr "χ"> +<!ENTITY b.thetas "θ"> +<!ENTITY ecaron "ě"> +<!ENTITY Odblac "Ő"> +<!ENTITY fflig "ff"> +<!ENTITY lowast "∗"> +<!ENTITY nvdash "⊬"> +<!ENTITY frac18 "⅛"> +<!ENTITY sup1 "¹"> +<!ENTITY njcy "њ"> +<!ENTITY b.thetav "ϑ"> +<!ENTITY sup2 "²"> +<!ENTITY gimel "ℷ"> +<!ENTITY ldot "⋖"> +<!ENTITY Ccedil "Ç"> +<!ENTITY rdquo "”"> +<!ENTITY rhard "⇁"> +<!ENTITY nsime "≄"> +<!ENTITY boxhu "┴"> +<!ENTITY intcal "⊺"> +<!ENTITY nsupe "⊉"> +<!ENTITY Gt "≫"> +<!ENTITY igr "ι"> +<!ENTITY nabla "∇"> +<!ENTITY urcorn "⌝"> +<!ENTITY nle "≰"> +<!ENTITY Icy "И"> +<!ENTITY DJcy "Ђ"> +<!ENTITY jukcy "є"> +<!ENTITY lceil "⌈"> +<!ENTITY oS "Ⓢ"> +<!ENTITY malt "✠"> +<!ENTITY ccirc "ĉ"> +<!ENTITY ycirc "ŷ"> +<!ENTITY Aacgr "Ά"> +<!ENTITY Ntilde "Ñ"> +<!ENTITY vsupnE "⊋"> +<!ENTITY ogr "ο"> +<!ENTITY and "∧"> +<!ENTITY gvnE "≩"> +<!ENTITY dashv "⊣"> +<!ENTITY supE "⊇"> +<!ENTITY mu "μ"> +<!ENTITY vsubnE ""> +<!ENTITY gE "≧"> +<!ENTITY smid ""> +<!ENTITY delta "δ"> +<!ENTITY tcaron "ť"> +<!ENTITY rsqb "]"> +<!ENTITY bull "•"> +<!ENTITY cuwed "⋏"> +<!ENTITY raquo "»"> +<!ENTITY frac45 "⅘"> +<!ENTITY part "∂"> +<!ENTITY Vdash "⊩"> +<!ENTITY boxhd "┬"> +<!ENTITY psi "ψ"> +<!ENTITY b.Omega "Ω"> +<!ENTITY iquest "¿"> +<!ENTITY sqcup "⊔"> +<!ENTITY YUcy "Ю"> +<!ENTITY psgr "ψ"> +<!ENTITY conint "∮"> +<!ENTITY gel "⋛"> +<!ENTITY Icirc "Î"> +<!ENTITY twixt "≬"> +<!ENTITY boxHD "╥"> +<!ENTITY male "♂"> +<!ENTITY euro "€"> +<!ENTITY epsi "∊"> +<!ENTITY Rcaron "Ř"> +<!ENTITY SHCHcy "Щ"> +<!ENTITY ugr "υ"> +<!ENTITY Phi "Φ"> +<!ENTITY b.Xi "Ξ"> +<!ENTITY lt "&#60;"> +<!ENTITY scnsim "⋩"> +<!ENTITY models "⊧"> +<!ENTITY boxHu "╩"> +<!ENTITY Lcy "Л"> +<!ENTITY Sacute "Ś"> +<!ENTITY nwarr "↖"> +<!ENTITY drcorn "⌟"> +<!ENTITY NJcy "Њ"> +<!ENTITY mumap "⊸"> +<!ENTITY rAarr "⇛"> +<!ENTITY nsubE "⊈"> +<!ENTITY b.rho "ρ"> +<!ENTITY oelig "œ"> +<!ENTITY utrif "▴"> +<!ENTITY subne "⊊"> +<!ENTITY para "¶"> +<!ENTITY ocirc "ô"> +<!ENTITY ouml "ö"> +<!ENTITY num "#"> +<!ENTITY boxUL "╛"> +<!ENTITY IEcy "Е"> +<!ENTITY Ocy "О"> +<!ENTITY Ugrave "Ù"> +<!ENTITY eogon "ę"> +<!ENTITY sum "∑"> +<!ENTITY mcy "м"> +<!ENTITY YIcy "Ї"> +<!ENTITY Gamma "Γ"> +<!ENTITY isin "∊"> +<!ENTITY cuesc "⋟"> +<!ENTITY b.Pi "Π"> +<!ENTITY Ubreve "Ŭ"> +<!ENTITY starf "★"> +<!ENTITY gne "≩"> +<!ENTITY gammad "Ϝ"> +<!ENTITY napos "ʼn"> +<!ENTITY sup "⊃"> +<!ENTITY dArr "⇓"> +<!ENTITY Larr "↞"> +<!ENTITY nVDash "⊯"> +<!ENTITY boxhU "╧"> +<!ENTITY Ggr "Γ"> +<!ENTITY Idigr "Ϊ"> +<!ENTITY AElig "Æ"> +<!ENTITY Idot "İ"> +<!ENTITY Lacute "Ĺ"> +<!ENTITY sharp "♯"> +<!ENTITY Ubrcy "Ў"> +<!ENTITY lsqb "["> +<!ENTITY micro "µ"> +<!ENTITY Sub "⋐"> +<!ENTITY agr "α"> +<!ENTITY nap "≉"> +<!ENTITY sfgr "ς"> +<!ENTITY block "█"> +<!ENTITY nspar "∦"> +<!ENTITY supnE "⊋"> +<!ENTITY prsim "≾"> +<!ENTITY shcy "ш"> +<!ENTITY dblac "˝"> +<!ENTITY xhArr "↔"> +<!ENTITY dtri "▿"> +<!ENTITY barwed "⊼"> +<!ENTITY zcy "з"> +<!ENTITY agrave "à"> +<!ENTITY par "∥"> +<!ENTITY vsupne "⊋"> +<!ENTITY Scy "С"> +<!ENTITY zdot "ż"> +<!ENTITY rsquor "‘"> +<!ENTITY Delta "Δ"> +<!ENTITY nVdash "⊮"> +<!ENTITY Pgr "Π"> +<!ENTITY gamma "γ"> +<!ENTITY tau "τ"> +<!ENTITY Ecirc "Ê"> +<!ENTITY sung "♩"> +<!ENTITY natur "♮"> +<!ENTITY or "∨"> +<!ENTITY vsubne "⊊"> +<!ENTITY Jcy "Й"> +<!ENTITY square "□"> +<!ENTITY b.zeta "ζ"> +<!ENTITY b.Psi "Ψ"> +<!ENTITY gbreve "ğ"> +<!ENTITY Kcedil "Ķ"> +<!ENTITY ohm "Ω"> +<!ENTITY frac35 "⅗"> +<!ENTITY ssetmn "∖"> +<!ENTITY boxUR "╘"> +<!ENTITY frac34 "¾"> +<!ENTITY target "⌖"> +<!ENTITY cularr "↶"> +<!ENTITY xcirc "○"> +<!ENTITY boxhD "╤"> +<!ENTITY iecy "е"> +<!ENTITY Euml "Ë"> +<!ENTITY half "½"> +<!ENTITY rang "〉"> +<!ENTITY numero "№"> +<!ENTITY Ugr "Υ"> +<!ENTITY times "×"> +<!ENTITY semi ";"> +<!ENTITY rharu "⇀"> +<!ENTITY iocy "ё"> +<!ENTITY b.gammad "Ϝ"> +<!ENTITY thinsp " "> +<!ENTITY lozf "✦"> +<!ENTITY plusb "⊞"> +<!ENTITY tilde "˜"> +<!ENTITY Aogon "Ą"> +<!ENTITY Eogon "Ę"> +<!ENTITY blk12 "▒"> +<!ENTITY pre "≼"> +<!ENTITY boxHd "╦"> +<!ENTITY piv "ϖ"> +<!ENTITY ncaron "ň"> +<!ENTITY wcirc "ŵ"> +<!ENTITY utri "▵"> +<!ENTITY Prime "″"> +<!ENTITY cedil "¸"> +<!ENTITY idigr "ϊ"> +<!ENTITY curren "¤"> +<!ENTITY laquo "«"> +<!ENTITY ulcrop "⌏"> +<!ENTITY ring "˚"> +<!ENTITY oacute "ó"> +<!ENTITY Nacute "Ń"> +<!ENTITY permil "‰"> +<!ENTITY oacgr "ό"> +<!ENTITY b.phis "φ"> +<!ENTITY frac78 "⅞"> +<!ENTITY blk34 "▓"> +<!ENTITY gnsim "⋧"> +<!ENTITY boxVH "╫"> +<!ENTITY zhcy "ж"> +<!ENTITY b.phiv "ϕ"> +<!ENTITY loz "◊"> +<!ENTITY Ngr "Ν"> +<!ENTITY phgr "φ"> +<!ENTITY b.iota "ι"> +<!ENTITY ETH "Ð"> +<!ENTITY trade "™"> +<!ENTITY Cup "⋓"> +<!ENTITY subnE "⊊"> +<!ENTITY PHgr "Φ"> +<!ENTITY xi "ξ"> +<!ENTITY Rcy "Р"> +<!ENTITY ggr "γ"> +<!ENTITY Lmidot "Ŀ"> +<!ENTITY Scirc "Ŝ"> +<!ENTITY rtrif "▸"> +<!ENTITY larrtl "↢"> +<!ENTITY eDot "≑"> +<!ENTITY boxVL "╢"> +<!ENTITY THgr "Θ"> +<!ENTITY Dstrok "Đ"> +<!ENTITY cent "¢"> +<!ENTITY odash "⊝"> +<!ENTITY boxUl "╜"> +<!ENTITY ape "≊"> +<!ENTITY gEl "⋛"> +<!ENTITY nltri "⋪"> +<!ENTITY Aacute "Á"> +<!ENTITY cuvee "⋎"> +<!ENTITY gnE "≩"> +<!ENTITY kgr "κ"> +<!ENTITY iogon "į"> +<!ENTITY rarrtl "↣"> +<!ENTITY sccue "≽"> +<!ENTITY IOcy "Ё"> +<!ENTITY sext "✶"> +<!ENTITY uplus "⊎"> +<!ENTITY ecolon "≕"> +<!ENTITY nlArr "⇍"> +<!ENTITY scap "≿"> +<!ENTITY rarrlp "↬"> +<!ENTITY ngE "≱"> +<!ENTITY nsim "≁"> +<!ENTITY Acy "А"> +<!ENTITY emacr "ē"> +<!ENTITY Jcirc "Ĵ"> +<!ENTITY ltimes "⋉"> +<!ENTITY Bcy "Б"> +<!ENTITY b.Sigma "Σ"> +<!ENTITY cup "∪"> +<!ENTITY fork "⋔"> +<!ENTITY frac25 "⅖"> +<!ENTITY setmn "∖"> +<!ENTITY bsol "\"> +<!ENTITY Ycy "Ы"> +<!ENTITY b.Phi "Φ"> +<!ENTITY Gcedil "Ģ"> +<!ENTITY frac23 "⅔"> +<!ENTITY Iogon "Į"> +<!ENTITY blank "␣"> +<!ENTITY vprop "∝"> +<!ENTITY boxVR "╟"> +<!ENTITY ecy "э"> +<!ENTITY OHacgr "Ώ"> +<!ENTITY yen "¥"> +<!ENTITY hairsp " "> +<!ENTITY plusdo "∔"> +<!ENTITY lvnE "≨"> +<!ENTITY boxUr "╚"> +<!ENTITY breve "˘"> +<!ENTITY rtimes "⋊"> +<!ENTITY gnap ""> +<!ENTITY rtrie "⊵"> +<!ENTITY Mcy "М"> +<!ENTITY chi "χ"> +<!ENTITY tdot "⃛"> +<!ENTITY PSgr "Ψ"> +<!ENTITY Umacr "Ū"> +<!ENTITY caret "⁁"> +<!ENTITY xutri "△"> +<!ENTITY CHcy "Ч"> +<!ENTITY djcy "ђ"> +<!ENTITY lambda "λ"> +<!ENTITY Tstrok "Ŧ"> +<!ENTITY puncsp " "> +<!ENTITY Ll "⋘"> +<!ENTITY aacgr "ά"> +<!ENTITY xdtri "▽"> +<!ENTITY GJcy "Ѓ"> +<!ENTITY gdot "ġ"> +<!ENTITY sub "⊂"> +<!ENTITY mid "∣"> +<!ENTITY dzcy "џ"> +<!ENTITY igrave "ì"> +<!ENTITY Emacr "Ē"> +<!ENTITY Rcedil "Ŗ"> +<!ENTITY gt ">"> +<!ENTITY larrlp "↫"> +<!ENTITY harr "↔"> +<!ENTITY thgr "θ"> +<!ENTITY map "↦"> +<!ENTITY drarr "↘"> +<!ENTITY boxVh "╬"> +<!ENTITY ijlig "ij"> +<!ENTITY tcedil "ţ"> +<!ENTITY dlcrop "⌍"> +<!ENTITY prnsim "⋨"> +<!ENTITY ecir "≖"> +<!ENTITY rgr "ρ"> +<!ENTITY deg "°"> +<!ENTITY lap "≲"> +<!ENTITY KJcy "Ќ"> +<!ENTITY Cdot "Ċ"> +<!ENTITY Uogon "Ų"> +<!ENTITY not "¬"> +<!ENTITY dash "‐"> +<!ENTITY nexist "∄"> +<!ENTITY Lt "≪"> +<!ENTITY b.Upsi "ϒ"> +<!ENTITY Atilde "Ã"> +<!ENTITY edot "ė"> +<!ENTITY Ncedil "Ņ"> +<!ENTITY els "⋜"> +<!ENTITY erDot "≓"> +<!ENTITY boxVl "╣"> +<!ENTITY scy "с"> +<!ENTITY ulcorn "⌜"> +<!ENTITY eacgr "έ"> +<!ENTITY Itilde "Ĩ"> +<!ENTITY Zacute "Ź"> +<!ENTITY xharr "↔"> +<!ENTITY gl "≷"> +<!ENTITY chcy "ч"> +<!ENTITY Oacute "Ó"> +<!ENTITY itilde "ĩ"> +<!ENTITY Ycirc "Ŷ"> +<!ENTITY nhArr "⇎"> +<!ENTITY Lstrok "Ł"> +<!ENTITY divide "÷"> +<!ENTITY Tcy "Т"> +<!ENTITY Jukcy "Є"> +<!ENTITY Yacute "Ý"> +<!ENTITY boxv "│"> +<!ENTITY hamilt "ℋ"> +<!ENTITY nu "ν"> +<!ENTITY ngt "≯"> +<!ENTITY jsercy "ј"> +<!ENTITY uml "¨"> +<!ENTITY KHgr "Χ"> +<!ENTITY lstrok "ł"> +<!ENTITY nsupE "⊉"> +<!ENTITY dtrif "▾"> +<!ENTITY vellip "⋮"> +<!ENTITY rceil "⌉"> +<!ENTITY ell "ℓ"> +<!ENTITY Ecy "Э"> +<!ENTITY Jsercy "Ј"> +<!ENTITY ljcy "љ"> +<!ENTITY Kgr "Κ"> +<!ENTITY ngr "ν"> +<!ENTITY sigmav "ς"> +<!ENTITY Gdot "Ġ"> +<!ENTITY rdquor "“"> +<!ENTITY prnap "⋨"> +<!ENTITY tcy "т"> +<!ENTITY frac12 "½"> +<!ENTITY telrec "⌕"> +<!ENTITY vdash "⊢"> +<!ENTITY Zgr "Ζ"> +<!ENTITY Auml "Ä"> +<!ENTITY Ocirc "Ô"> +<!ENTITY uogon "ų"> +<!ENTITY hArr "⇔"> +<!ENTITY nge "≱"> +<!ENTITY iacute "í"> +<!ENTITY Cacute "Ć"> +<!ENTITY Omacr "Ō"> +<!ENTITY equiv "≡"> +<!ENTITY vltri "⊲"> +<!ENTITY eta "η"> +<!ENTITY SHcy "Ш"> +<!ENTITY percnt "&#x25;"> +<!ENTITY lowbar "_"> +<!ENTITY frac16 "⅙"> +<!ENTITY lrarr2 "⇆"> +<!ENTITY nles "≰"> +<!ENTITY bump "≎"> +<!ENTITY veebar "⊻"> +<!ENTITY Wcirc "Ŵ"> +<!ENTITY frac15 "⅕"> +<!ENTITY bumpe "≏"> +<!ENTITY egrave "è"> +<!ENTITY frac14 "¼"> +<!ENTITY supe "⊇"> +<!ENTITY rfloor "⌋"> +<!ENTITY Dgr "Δ"> +<!ENTITY frac13 "⅓"> +<!ENTITY ge "≥"> +<!ENTITY boxVr "╠"> +<!ENTITY pgr "π"> +<!ENTITY kgreen "ĸ"> +<!ENTITY boxh "─"> +<!ENTITY Lambda "Λ"> +<!ENTITY ugrave "ù"> +<!ENTITY emsp13 " "> +<!ENTITY becaus "∵"> +<!ENTITY sce "≽"> +<!ENTITY grave "`"> +<!ENTITY zeta "ζ"> +<!ENTITY b.Theta "Θ"> +<!ENTITY eth "ð"> +<!ENTITY Ouml "Ö"> +<!ENTITY check "✓"> +<!ENTITY hybull "⁃"> +<!ENTITY Gg "⋙"> +<!ENTITY Ccaron "Č"> +<!ENTITY plus "+"> +<!ENTITY fllig "fl"> +<!ENTITY forall "∀"> +<!ENTITY dcaron "ď"> +<!ENTITY gacute "ǵ"> +<!ENTITY sc "≻"> +<!ENTITY OHgr "Ω"> +<!ENTITY emsp14 " "> +<!ENTITY hellip "…"> +<!ENTITY lhard "↽"> +<!ENTITY sstarf "⋆"> +<!ENTITY samalg "∐"> +<!ENTITY EEgr "Η"> +<!ENTITY rhov "ϱ"> +<!ENTITY b.epsi "ε"> +<!ENTITY lsquo "‘"> +]> +<book id="jboss_portal_reference_guide"> +<!--<book lang="en"> + <bookinfo> + <title>JBoss Portal Reference Guide</title> + <subtitle>JBoss Portal Reference Guide</subtitle> + <edition>2.7.0</edition> + <pubsnumber>1</pubsnumber> + <productname>JBoss Portal</productname> + <productnumber>2.7</productnumber> + <pubdate>Nov, 2007</pubdate> + <isbn>N/A</isbn> + + + <abstract><para>This document is an outline of the information plan for JBoss AS 5 GA project's documentation.</para></abstract> + + + + + + + + <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </bookinfo> + --> + <!--<toc/>--> + <bookinfo id="JBoss_Portal_Reference_Guide"> + <title>JBoss Portal Reference Guide</title> + <subtitle>JBoss Portal 2.7 Reference Guide</subtitle> + <edition>2</edition> + <pubsnumber>7</pubsnumber> + <productname>JBoss Portal</productname> + <productnumber>2.7</productnumber> + <pubdate>Oct, 2007</pubdate> + <isbn>N/A</isbn> + <issuenum>1</issuenum> + + + <abstract><para>This book is a JBoss Portal 2.7 Reference Guide.</para> + </abstract> + <corpauthor> + <inlinemediaobject> + <imageobject> + <imagedata fileref="Common_Content/images/redhat-logo.svg"/> + </imageobject> + </inlinemediaobject> + </corpauthor> + + <copyright> + <year>&YEAR;</year> + <holder>&HOLDER;</holder> + </copyright> + <legalnotice xml:base="Common_Content/Legal_Notice.xml"> + <para> + Copyright <trademark class="copyright"/> &YEAR; &HOLDER;. This material may only be distributed subject to the terms and conditions set forth in the Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License (which is presently available at <ulink url="http://creativecommons.org/licenses/by-nc-sa/3.0/">http...>). + </para> + <para> + Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other countries. + </para> + <para> + All other trademarks referenced herein are the property of their respective owners. + </para> + <para> + The GPG fingerprint of the security(a)redhat.com key is: + </para> + <para> + CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E + </para> + <para> + <address> + <street>1801 Varsity Drive</street> + <city>Raleigh</city>, <state>NC</state> <postcode>27606-2072</postcode><country>USA</country><phone>Phone: +1 919 754 3700</phone> + <phone>Phone: 888 733 4281</phone> + <fax>Fax: +1 919 754 3701</fax> + <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state> <postcode>27709</postcode><country>USA</country> + </address> + </para> +</legalnotice> + <authorgroup><corpauthor> JBoss Portal Team </corpauthor> + + +<author> + <firstname>Thomas</firstname> + <surname>Heute</surname> + <email&gt;theute(a)jboss.org&lt;/email&gt; + </author> + <author> + <firstname>Julien</firstname> + <surname>Viet</surname> + <email&gt;julien(a)jboss.org&lt;/email&gt; + </author> + <author> + <firstname>Roy</firstname> + <surname>Russo</surname> + </author> + <author> + <firstname>Boleslaw</firstname> + <surname>Dawidowicz</surname> + <email>boleslaw dot dawidowicz at redhat dot com</email> + </author> + <author> + <firstname>Chris</firstname> + <surname>Laprun</surname> + <email&gt;chris.laprun(a)jboss.com&lt;/email&gt; + </author> + <author> + <firstname>Murray</firstname> + <surname>McAllister</surname> + <email&gt;mmcallis(a)redhat.com&lt;/email&gt; + </author> + + + +</authorgroup> +</bookinfo> + + <preface id="trademarks"> + <title>Please Read: Important Trademark Information</title> + <para> + Sun, JavaServer, JSP, Java, JMX, JDK, Java runtime environment, J2EE, JVM, Javadoc, 100% Pure Java, JDBC, and JavaScript are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. + </para> + <para> + JBoss is a registered trademark of Red Hat, Inc. in the U.S. and other countries. + </para> + <para> + Red Hat is a registered trademark of Red Hat, Inc. in the United States and other countries. + </para> + <para> + Oracle is a registered trademark of Oracle International Corporation. + </para> + <para> + Microsoft, Windows, Active Directory, and SQL Server are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. + </para> + <para> + Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries. + </para> + <para> + UNIX is a registered trademark of The Open Group. + </para> + <para> + MySQL is a trademark or registered trademark of MySQL AB in the U.S. and other countries. + </para> + <para> + Apache is a trademark of The Apache Software Foundation. + </para> + <para> + Mac and Mac OS are trademarks of Apple Inc., registered in the U.S. and other countries. + </para> + <para> + All other trademarks referenced herein are the property of their respective owners. + </para> +</preface><!--To do: + +Apache? + +Linux? + + +All the sun stuff + + + +Microsoft? + + +Mail them first (see Apache Jackrabbit) + + + + + +'Apache is a trademark of The Apache Software Foundation, and is used with permission.' This is not necessary in the case of all-inclusive attribution language such as, 'All marks are the properties of their respective owners.' Contact the ASF Public Relations Committee <prc(a)apache.org&gt; with all inquiries regarding trademark issues --> +<!-- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Overview.xml" />--> +<!-- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Featurelist.xml" />--> + <preface id="target" revision="1"> + <title>Target Audience</title> + <para> + This guide is aimed towards portlet developers, portal administrators, and those wishing to + implement and extend the JBoss Portal framework. For end-user documentation, please refer to the JBoss Portal User Manual from the <ulink url="http://labs.jboss.com/portal/jbossportal/docs/index.html"&... Portal Documentation Library</ulink> + .</para> +</preface> +<!-- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Acknowledgements.xml" />--> + <chapter id="supportedversions"> + <!-- <chapterinfo> + <author> + <firstname>Thomas</firstname> + <surname>Heute</surname> + </author> + <author> + <firstname>Roy</firstname> + <surname>Russo</surname> + </author> + </chapterinfo>--> + <title>System Requirements</title> + <para> + The following chapter details hardware and software versions that are compatible with JBoss Portal. The hardware and software listed has either been tested, or reported as working by users. Before reporting a problem, make sure you are using compatible hardware and software. + </para> + <para> + If you successfully installed JBoss Portal on versions not listed here, please let us know so it can be added to this section. + </para> + <section> + <title>Minimum System Requirements</title> + <para> + <itemizedlist> + <listitem><para>JDK 5 (JDK 6 is not part of the test platform)</para></listitem> + <listitem><para>512 MB RAM</para></listitem> + <listitem><para>100 MB hard disk space</para></listitem> + <listitem><para>400 MHz CPU</para></listitem> + </itemizedlist> + </para> + </section> + <section> + <title>Supported Operating Systems</title> + <para>JBoss Portal is <trademark class="trade">100% Pure Java</trademark>, and therefore it is interoperable with most operating systems + capable of running a Java Virtual Machine (<trademark class="trade">JVM</trademark>), including <trademark class="registered">Linux</trademark>, <trademark class="registered">Windows</trademark>, <trademark class="registered">UNIX</trademark> operating systems, and Mac OS X. + </para> + </section> + <section> + <title>JBoss Application Server</title> + <para>JBoss Portal 2.7.0 is tested with JBoss Application Server (AS) JBoss AS 4.2.3, JBoss Enterprise Application Platform (EAP) 4.2 and JBoss EAP 4.3. It is highly recommended that customers who have access to the <ulink url="https://support.redhat.com/portal/login.html">JBoss Customer Support Portal (CSP)</ulink> use JBoss EAP 4.3. Customers who do not have access to the JBoss CSP should use <ulink url="http://labs.jboss.com/jbossas/">JBoss AS</ulink>. + </para> + <warning> + <para>JBoss AS versions 4.0.<replaceable>x</replaceable> are not supported.</para> + </warning> + </section> + <section id="supportedversions-db"> + <title>Databases</title> + <para>JBoss Portal is database-agnostic. The following list outlines known-to-be-working database vendor and version combinations:</para> + <itemizedlist> + <listitem><para><trademark class="registered">MySQL</trademark> 4 (use <ulink url="http://dev.mysql.com/downloads/connector/j/3.1.html">Co... 3.1</ulink>) and 5 (<ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=AvoidMySQL5DataTruncat... issue</ulink>)</para></listitem> + <listitem><para>PostgreSQL 8.<replaceable>x</replaceable></para></listitem> + <listitem><para>Hypersonic SQL</para></listitem> + <listitem><para>Apache Derby</para></listitem> + <listitem><para><trademark class="registered">Oracle</trademark> Database 9 and 10g (use the <ulink url="http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/i... driver from the Oracle 10 branch</ulink> even if you are running Oracle 9)</para></listitem> + <listitem><para><trademark class="registered">Microsoft</trademark><trademark class="registered"> SQL Server</trademark></para></listitem> + <listitem><para>MaxDB</para></listitem> + </itemizedlist> + <para>JBoss Portal employs Hibernate as an interface to a Relational Database Management System (RDBMS). Most Relational Database Management Systems supported by Hibernate will work with JBoss Portal.</para> + </section> + <section> + <title>Source Building</title> + <para>The source building mechanism works on Linux, Windows, Mac OS X, and UNIX operating systems.</para> + </section> +</chapter> + <chapter id="installation"> + <title>Installation</title> + <para> + Depending on your needs, there are several different methods to install JBoss + Portal. Pre-configured clustered versions ( + <computeroutput>JBoss Portal Binary (Clustered)</computeroutput> + ) are available from the + <ulink url="http://labs.jboss.com/portal/jbossportal/download/index.html&qu... + JBoss Portal Downloads + </ulink> + page. Clustered versions of JBoss Portal must be deployed in the + <filename>JBOSS_INSTALLATION_DIRECTORY/server/all/deploy/</filename> + directory. All JBoss AS instances must reference the same datasource. Refer to + <xref linkend="install_source_env"/> + for details on how to configure JBoss Portal for clustering. + </para> + <para> + An environment variable, + <computeroutput>JBOSS_HOME</computeroutput> + , is configured in + <xref linkend="install_source_env"/> + . References to + <computeroutput>$JBOSS_HOME</computeroutput> + assume this to be your + <replaceable>JBOSS_INSTALLATION_DIRECTORY</replaceable> + . + </para> + <section id="install_bundle"> + <title>The JBoss Portal and JBoss AS Bundle</title> + <para> + This is the easiest and fastest way to get JBoss Portal installed and running. + The JBoss Portal and JBoss AS bundle contains JBoss AS, JBoss Portal, and the + embedded Hypersonic SQL database. To install the JBoss Portal and JBoss AS + bundle: + </para> + <para> + <orderedlist> + <listitem> + <para> + <emphasis role="bold">Get the bundle:</emphasis> + the bundle is available from the + <ulink url="http://labs.jboss.com/portal/jbossportal/download/index.html&qu... + JBoss Portal Downloads + </ulink> + page. Bundles use the + <computeroutput>JBoss Portal + JBoss AS</computeroutput> + naming convention. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Extract the bundle:</emphasis> + extract the ZIP archive. It does not matter which directory is used. On + Windows, the recommended directory is + <filename> + C:\jboss- + <replaceable>version-number</replaceable> + </filename> + . + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Start the server:</emphasis> + change into the + <filename>JBOSS_PORTAL_INSTALLATION_DIRECTORY/bin/</filename> + directory. On Windows, execute + <command>run.bat</command> + . On Linux, run the + <command>sh run.sh</command> + command. To specify a configuration to use, for example, the default + configuration, append the + <command>-c default</command> + option to the + <command>run.bat</command> + or + <command>sh run.sh</command> + commands. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Log in to JBoss Portal:</emphasis> + using a Web browser, navigate to + <ulink url="http://localhost:8080/portal"/> + to open the JBoss Portal homepage. Log in using one of the two default + accounts: username + <emphasis>user</emphasis> + , password + <emphasis>user</emphasis> + , or username + <emphasis>admin</emphasis> + , password + <emphasis>admin</emphasis> + : + </para> + </listitem> + </orderedlist> + </para> + <para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/common/frontpage.png" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + <formalpara> + <title>SQL Errors</title> + <para> + Tables are automatically created the first time JBoss Portal starts. When + deployed for the first time, JBoss Portal checks for the existence of the + initial tables, which have not been created yet. This causes errors such as + the following, which can safely be ignored: + </para> + </formalpara> + <para> + <programlisting><![CDATA[ +WARN [JDBCExceptionReporter] SQL Error: -22, SQLState: S0002 +ERROR [JDBCExceptionReporter] Table not found in statement ... +WARN [JDBCExceptionReporter] SQL Error: 1146, SQLState: 42S02 +ERROR [JDBCExceptionReporter] Table 'jbossportal.jbp_cms_repositoryentry' doesn't exist +WARN [JDBCExceptionReporter] SQL Error: 1146, SQLState: 42S02 +ERROR [JDBCExceptionReporter] Table 'jbossportal.jbp_cms_version_refs' doesn't exist]]></programlisting> + </para> + </section> + <section id="install_binary"> + <title>Installing the Binary Download</title> + <para> + The binary package typically consists of the + <filename>jboss-portal.sar/</filename> + directory, documentation such as the JBoss Portal User Guide and the JBoss Portal + Reference Guide, and a set of pre-configured Datasource descriptors that allow + JBoss Portal to communicate with an external database. This installation method + is recommended for users who already have JBoss EAP or JBoss AS installed, or + those who need to install JBoss Portal in a clustered environment. + </para> + <section> + <title>Setting up your Environment</title> + <section id="install_binarydownload"> + <title>Getting the Binary</title> + <para> + The binary download is available from the + <ulink url="http://labs.jboss.com/portal/jbossportal/download/index.html&qu... + JBoss Portal Downloads + </ulink> + page. Look for the + <computeroutput>JBoss Portal Binary</computeroutput> + package. Once the binary ZIP file has been downloaded and extracted, the + folder hierarchy will look similar to the following: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/setup/package.png"/> + </imageobject> + </mediaobject> + </para> + <para> + Files contained in this download are used in later sections. Download and + extract the JBoss Portal binary ZIP file before proceeding. + </para> + </section> + <section> + <title>JBoss EAP and JBoss AS Setup</title> + <para> + Before deploying JBoss Portal, make sure you have JBoss EAP or JBoss AS + installed. Customers who have access to the + <ulink url="https://support.redhat.com/portal/login.html"> + JBoss Customer Support Portal (CSP) + </ulink> + are advised to download and install JBoss EAP 4.3. Customers who do not + have access to the JBoss CSP are advised to use + <ulink url="http://labs.jboss.com/jbossas/downloads/">JBoss AS</ulink> + . For JBoss AS installation instructions, please refer to the + <ulink url="http://labs.jboss.com/jbossas/docs/index.html"> + JBoss AS Installation Guide + </ulink> + . + </para> + <warning> + <title>Use the JBoss EAP and JBoss AS ZIP file</title> + <para> + Only use the JBoss EAP and JBoss AS ZIP file versions. + <emphasis role="bold"> + DO NOT ATTEMPT to deploy JBoss Portal on the installer version of + JBoss EAP or JBoss AS. + </emphasis> + </para> + </warning> + </section> + <section id="install_source_env_0"> + <title>Operating System Environment Settings</title> + <para> + For JBoss EAP, JBoss AS, and build targets to work, you must configure a + <filename>JBOSS_HOME</filename> + environment variable. This environment variable must point to the root + directory of the JBoss EAP or JBoss AS installation directory, which is the + directory where the JBoss EAP or JBoss AS files were extracted to. + </para> + <para> + On Windows, this is accomplished by going to + <emphasis> + Start &gt; Settings &gt; Control Panel &gt; System &gt; Advanced &gt; Environment + Variables + </emphasis> + . Under the + <emphasis>System Variables</emphasis> + section, click + <emphasis>New</emphasis> + . Set the + <filename>JBOSS_HOME</filename> + environment variable to the location of your JBoss EAP or JBoss AS + installation directory: + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/setup/win_envsetup.gif"/> + </imageobject> + </mediaobject> + </para> + <para> + To configure the + <filename>JBOSS_HOME</filename> + environment variable on Linux: + </para> + <para> + <orderedlist> + <listitem> + <para> + Add the following line to the + <filename>~/.bashrc</filename> + file. Note: this must be configured while logged in as the user + who runs JBoss EAP or JBoss AS: + </para> + <para> + <programlisting> + export JBOSS_HOME=/path/to/jboss/installation/ + </programlisting> + </para> + </listitem> + <listitem> + <para> + Run the following command to enable the + <filename>JBOSS_HOME</filename> + environment variable: + </para> + <para> + <programlisting>source ~/.bashrc</programlisting> + </para> + </listitem> + </orderedlist> + </para> + <note> + <title> + JBoss EAP + <filename>JBOSS_HOME</filename> + Environment Variable + </title> + <para> + If you are running JBoss EAP, configure the + <filename>JBOSS_HOME</filename> + environment variable to point to the + <filename> + /path/to/jboss-eap- + <replaceable>version</replaceable> + /jboss-as/ + </filename> + directory. + </para> + </note> + </section> + <section> + <title>Database Setup</title> + <para> + A database is required for JBoss Portal to run. JBoss EAP and JBoss AS + include an embedded Hypersonic SQL database that JBoss Portal can use; + however, this is only recommended for developer use. The following + databases are recommended for production use, and have had test suites run + against them: + <trademark class="registered">MySQL</trademark> + 4 and 5, + <trademark class="registered">Microsoft</trademark> + <trademark class="registered">SQL Server</trademark> + , PostgreSQL 8, and + <trademark class="registered">Oracle</trademark> + Database 9 and 10. JBoss Portal can use any database that is supported by + Hibernate. + </para> + <para>To configure a database to use with JBoss Portal:</para> + <para> + <orderedlist> + <listitem> + <para> + <emphasis role="bold">Create a new database:</emphasis> + this guide assumes that the new database is called + <emphasis>jbossportal</emphasis> + . + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold"> + Grant access rights for a user to the + <emphasis>jbossportal</emphasis> + database: + </emphasis> + JBoss Portal needs to create tables and modify table data. Grant + access rights to a desired user to the + <emphasis>jbossportal</emphasis> + database. Configure the same username and password in the + Datasource descriptor. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold"> + Deploy an RDBMS + <trademark class="trade">JDBC</trademark> + connector: + </emphasis> + an RDBMS JDBC connector is required for JBoss Portal to + communicate with a database. Copy the connector into the + <filename>$JBOSS_HOME/server/default/lib/</filename> + directory. For example, an RDBMS JDBC connector for MySQL can be + download from + <ulink url="http://www.mysql.com/products/connector/j/"/> + . For the correct RDMBS JDBC connector, please refer to the + database documentation. + </para> + </listitem> + </orderedlist> + </para> + </section> + <section> + <title>Datasource Descriptors</title> + <para> + The JBoss Portal binary download that was extracted in + <xref linkend="install_binarydownload"/> + , contains pre-configured Datasource descriptors for the more popular + databases. Datasource descriptors are provided for the MySQL 4 and 5, + PostgreSQL, Microsoft SQL Server, and Oracle databases, and can be found in + the + <filename>setup</filename> + subdirectory where the JBoss Portal binary was extracted to: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/setup/dsfiles.png"/> + </imageobject> + </mediaobject> + <para> + Copy the Datasource descriptor that matches your database into the + <filename> + $JBOSS_HOME/server/ + <replaceable>configuration</replaceable> + /deploy/ + </filename> + directory, where + <replaceable>configuration</replaceable> + is either all, default, minimal or production. The production configuration + only exists on JBoss EAP, and not JBoss AS. For example, if you are using + the all configuration, copy the Datasource descriptor into the + <filename>$JBOSS_HOME/server/all/deploy/</filename> + directory. + </para> + <para> + After the Datasource descriptor has been copied into the + <filename>deploy</filename> + directory, make sure the + <computeroutput>user-name</computeroutput> + , + <computeroutput>password</computeroutput> + , + <computeroutput>connection-url</computeroutput> + , and + <computeroutput>driver-class</computeroutput> + , are correct for your chosen database. Datasource descriptor files can be + deployed to test before being used in production. The following is an + example Datasource descriptor for a PostgreSQL database: + </para> + <programlisting role="XML"> + <![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<datasources> + <local-tx-datasource> + <jndi-name>PortalDS</jndi-name> + <connection-url>jdbc:postgresql:jbossportal</connection-url> + <driver-class>org.postgresql.Driver</driver-class> + <user-name>portal</user-name> + <password>portalpassword</password> + </local-tx-datasource> +</datasources>]]></programlisting> + <para> + For further details about Datasource descriptors, please refer to the + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=CreateAJDBCDataSource&... + JBoss JDBC Datasource Wiki page + </ulink> + . + </para> + </section> + </section> + <section> + <title>Deploying JBoss Portal</title> + <para>To start JBoss EAP or JBoss AS and deploy JBoss Portal:</para> + <para> + <orderedlist> + <listitem> + <para> + <emphasis role="bold">Datasource descriptor:</emphasis> + if you have not done so already, change into the + <filename>setup</filename> + subdirectory where the JBoss Portal binary was extracted to. Copy the + correct Datasource descriptor file ( + <filename>*-ds.xml</filename> + ) you modified in the previous steps into the + <filename> + $JBOSS_HOME/server/ + <replaceable>configuration</replaceable> + /deploy/ + </filename> + directory. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Start the server:</emphasis> + change into the + <filename>$JBOSS_HOME/bin/</filename> + directory. On Windows, execute + <command>run.bat</command> + . On Linux, run the + <command>sh run.sh</command> + command. To specify a configuration to use, for example, the default + configuration, append the + <command>-c default</command> + option to the + <command>run.bat</command> + or + <command>sh run.sh</command> + commands. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Log in to JBoss Portal:</emphasis> + using a Web browser, navigate to + <ulink url="http://localhost:8080/portal"/> + to open the JBoss Portal homepage. Log in using one of the two + default accounts: username + <emphasis>user</emphasis> + , password + <emphasis>user</emphasis> + , or username + <emphasis>admin</emphasis> + , password + <emphasis>admin</emphasis> + . + </para> + </listitem> + </orderedlist> + </para> + <formalpara> + <title>SQL Errors</title> + <para> + Tables are automatically created the first time JBoss Portal starts. When + deployed for the first time, JBoss Portal checks for the existence of the + initial tables, which have not been created yet. This causes errors such as + the following, which can safely be ignored: + </para> + </formalpara> + <para> + <programlisting><![CDATA[ +WARN [JDBCExceptionReporter] SQL Error: -22, SQLState: S0002 +ERROR [JDBCExceptionReporter] Table not found in statement ... +WARN [JDBCExceptionReporter] SQL Error: 1146, SQLState: 42S02 +ERROR [JDBCExceptionReporter] Table 'jbossportal.jbp_cms_repositoryentry' doesn't exist +WARN [JDBCExceptionReporter] SQL Error: 1146, SQLState: 42S02 +ERROR [JDBCExceptionReporter] Table 'jbossportal.jbp_cms_version_refs' doesn't exist +]]></programlisting> + </para> + </section> + </section> + <section id="install_source"> + <title>Installing from the Sources</title> + <section> + <title>Getting the Sources</title> + <para> + The JBoss Portal source files can be obtained from the + <ulink url="http://labs.jboss.com/portal/jbossportal/download/index.html&qu... + JBoss Portal Downloads + </ulink> + page. The source files download uses a + <filename>JBoss Portal Source Code</filename> + naming convention. As well, the sources can be obtained from SVN. The latest + sources for the 2.7. + <replaceable>x</replaceable> + versions are located at + <ulink url="http://anonsvn.jboss.org/repos/portal/branches/JBoss_Portal_Bra... + . + </para> + <para> + Several modules have been extracted from the JBoss Portal SVN repository. + These modules have a different lifecycle and a different version scheme. The + following is a list of modules used in JBoss Portal 2.7.0, and the locations + of their source code: + </para> + <para> + <itemizedlist> + <listitem> + <para> + JBoss Portal Common 1.2.1: + <emphasis> + http://anonsvn.jboss.org/repos/portal/modules/common/tags/JBP_COMMON_1_2_1 + </emphasis> + </para> + </listitem> + <listitem> + <para> + JBoss Portal Web 1.2.1: + <emphasis> + http://anonsvn.jboss.org/repos/portal/modules/web/tags/JBP_WEB_1_2_1 + </emphasis> + </para> + </listitem> + <listitem> + <para> + JBoss Portal Test 1.0.3: + <emphasis> + http://anonsvn.jboss.org/repos/portal/modules/test/tags/JBP_TEST_1_0_3 + </emphasis> + </para> + </listitem> + <listitem> + <para> + JBoss Portal Portlet 2.0.3: + <emphasis> + http://anonsvn.jboss.org/repos/portal/modules/portlet/tags/JBP_PORTLET_2_0_3 + </emphasis> + </para> + </listitem> + <listitem> + <para> + JBoss Portal Identity 1.0.4: + <emphasis> + http://anonsvn.jboss.org/repos/portal/modules/identity/tags/JBP_IDENTITY_... + </emphasis> + </para> + </listitem> + <listitem> + <para> + JBoss Portal CMS 1.2.0: + <emphasis> + http://anonsvn.jboss.org/repos/portal/modules/cms/tags/JBP_CMS_1_2_0 + </emphasis> + </para> + </listitem> + </itemizedlist> + </para> + <para> + After checking out the source from SVN, or after extracting the + <filename>JBoss Portal Source Code</filename> + ZIP file, a directory structure similar to the following will be created: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/setup/svncodir.png"/> + </imageobject> + </mediaobject> + <para> + If the source files were obtained from SVN, change into the + <filename>trunk/src/</filename> + directory to see the directories from the above image. As well, there is an + empty + <filename>thirdparty</filename> + directory. This directory contains files after building the JBoss Portal + source code (refer to + <xref linkend="building_deploying_from_source"/> + ). For more information about the JBoss Portal SVN repository, and accessing + different versions of the JBoss Portal codebase, refer to the + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=PortalSVNRepo"> + JBoss Portal SVN Repo + </ulink> + page on the JBoss Wiki. + </para> + </section> + <section> + <title>JBoss EAP and JBoss AS Setup</title> + <section> + <title>JBoss Application Server Setup</title> + <para> + Before deploying JBoss Portal, make sure you have JBoss EAP or JBoss AS + installed. Customers who have access to the + <ulink url="https://support.redhat.com/portal/login.html"> + JBoss Customer Support Portal (CSP) + </ulink> + are advised to download and install JBoss EAP 4.3. Customers who do not + have access to the JBoss CSP are advised to use + <ulink url="http://labs.jboss.com/jbossas/downloads/">JBoss AS</ulink> + . For JBoss AS installation instructions, please refer to the + <ulink url="http://labs.jboss.com/jbossas/docs/index.html"> + JBoss AS Installation Guide + </ulink> + . + </para> + <warning> + <title>Use the JBoss EAP and JBoss AS ZIP file</title> + <para> + Only use the JBoss EAP and JBoss AS ZIP file versions. + <emphasis role="bold"> + DO NOT ATTEMPT to deploy JBoss Portal on the installer version of + JBoss EAP or JBoss AS. + </emphasis> + We are currently working on aligning the Application installer with + JBoss Portal. + </para> + </warning> + </section> + <section id="install_source_env"> + <title>Operating System Environment Settings</title> + <para> + For JBoss EAP, JBoss AS, and build targets to work, you must configure a + <filename>JBOSS_HOME</filename> + environment variable. This environment variable must point to the root + directory of the JBoss EAP or JBoss AS installation directory, which is the + directory where the JBoss EAP or JBoss AS files were extracted to. + </para> + <para> + On Windows, this is accomplished by going to + <emphasis> + Start &gt; Settings &gt; Control Panel &gt; System &gt; Advanced &gt; Environment + Variables + </emphasis> + . Under the + <emphasis>System Variables</emphasis> + section, click + <emphasis>New</emphasis> + . Set the + <filename>JBOSS_HOME</filename> + environment variable to the location of your JBoss EAP or JBoss AS + installation directory: + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/setup/win_envsetup.gif"/> + </imageobject> + </mediaobject> + </para> + <para> + To configure the + <filename>JBOSS_HOME</filename> + environment variable on Linux: + </para> + <para> + <orderedlist> + <listitem> + <para> + Add the following line to the + <filename>~/.bashrc</filename> + file. Note: this must be configured while logged in as the user + who runs JBoss EAP or JBoss AS: + </para> + <para> + <programlisting> + export JBOSS_HOME=/path/to/jboss/installation/ + </programlisting> + </para> + </listitem> + <listitem> + <para> + Run the following command to enable the + <filename>JBOSS_HOME</filename> + environment variable: + </para> + <para> + <programlisting>source ~/.bashrc</programlisting> + </para> + </listitem> + </orderedlist> + </para> + <note> + <title> + JBoss EAP + <filename>JBOSS_HOME</filename> + Environment Variable + </title> + <para> + If you are running JBoss EAP, configure the + <filename>JBOSS_HOME</filename> + environment variable to point to the + <filename> + /path/to/jboss-eap- + <replaceable>version</replaceable> + /jboss-as/ + </filename> + directory. + </para> + </note> + </section> + </section> + <section id="building_deploying_from_source"> + <title>Building and Deploying from the Sources</title> + <para> + During the first build, third-party libraries are obtained from an online + repository, so you must be connected to the Internet, and if you are behind a + proxy server, you need to define your proxy server address and proxy server + port number. To define a proxy server, add the following line to the + <filename>$JBOSS_HOME/bin/run.conf</filename> + file: + </para> + +<!--<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extras/runconf_javaops.xmlt"/>--> +<programlisting>JAVA_OPTS=-Dhttp.proxyHost=&lt;proxy-hostname&gt; -Dhttp.proxyPort=&lt;proxy-port&gt;</programlisting> + + <para> + Replace + <replaceable>proxy-hostname</replaceable> + with the proxy server's hostname, and + <replaceable>proxy-port</replaceable> + with the correct proxy server port number. + </para> + <para> + To build and deploy JBoss Portal from the sources, change into the + <filename>JBOSS_PORTAL_SOURCE_DIRECTORY/build/</filename> + directory, where + <filename>JBOSS_PORTAL_SOURCE_DIRECTORY</filename> + is the directory where the JBoss Portal source code was downloaded to. Then, + Windows users need to run the + <command>build.bat deploy</command> + command, and Linux users need to run the + <command>sh build.sh deploy</command> + command. + </para> + <para> + At the end of the build process, the + <filename>jboss-portal.sar</filename> + file is copied into the + <filename>$JBOSS_HOME/server/default/deploy/</filename> + directory: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/setup/build_deploy.png" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + <para> + <note> + <title>Portal Modules</title> + <para> + The previous steps install a bare version of JBoss Portal. In previous + versions, several additional modules were deployed as well, but this has + since been modularized to provide greater flexibility. To deploy + additional modules, refer to the + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=PortalModules"> + Portal's module list + </ulink> + for more information. To deploy all modules at once, change into the + <filename>build</filename> + directory. If you are running Linux, run the + <command>sh build.sh deploy-all</command> + command. On Windows, run the + <command>build.bat deploy-all</command> + command. + </para> + </note> + </para> + <para>To build the clustered version on Linux operating systems:</para> + <para> + <orderedlist> + <listitem> + <para> + Change into the + <filename>JBOSS_PORTAL_SOURCE_DIRECTORY/build/</filename> + directory, and run the following command: + </para> + <para> + <programlisting>sh build.sh main</programlisting> + </para> + </listitem> + <listitem> + <para> + Change into the + <filename>JBOSS_PORTAL_SOURCE_DIRECTORY/core/</filename> + directory, and run the following command: + </para> + <para> + <programlisting>sh build.sh deploy-ha</programlisting> + </para> + <para> + After the + <command>sh build.sh deploy-ha</command> + command completes, the + <filename>jboss-portal-ha.sar</filename> + file is copied into the + <filename>$JBOSS_HOME/server/all/deploy/</filename> + directory. + </para> + </listitem> + </orderedlist> + </para> + <para> + To build the clustered version on Windows, repeat the previous steps, + replacing + <command>sh build.sh</command> + with + <command>build.bat</command> + . + </para> + </section> + <section> + <title>Database Setup</title> + <para> + A database is required for JBoss Portal to run. JBoss EAP and JBoss AS include + an embedded Hypersonic SQL database that JBoss Portal can use; however, this + is only recommended for developer use. The following databases are recommended + for production use, and have had test suites run against them: MySQL 4 and 5, + Microsoft SQL Server, PostgreSQL 8, and Oracle Database 9 and 10. JBoss Portal + can use any database that is supported by Hibernate. + </para> + <para>To configure a database to use with JBoss Portal:</para> + <para> + <orderedlist> + <listitem> + <para> + <emphasis role="bold">Create a new database:</emphasis> + this guide assumes that the new database is called + <emphasis>jbossportal</emphasis> + . + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold"> + Grant access rights for a user to the + <emphasis>jbossportal</emphasis> + database: + </emphasis> + JBoss Portal needs to create tables and modify table data. Grant + access rights to a desired user to the + <emphasis>jbossportal</emphasis> + database. Configure the same username and password in the Datasource + descriptor. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Deploy an RDBMS JDBC connector:</emphasis> + an RDBMS JDBC connector is required for JBoss Portal to communicate + with a database. Copy the connector into the + <filename>$JBOSS_HOME/server/default/lib/</filename> + directory. For example, an RDBMS JDBC connector for MySQL can be + download from + <ulink url="http://www.mysql.com/products/connector/j/"/> + . For the correct RDMBS JDBC connector, please refer to the database + documentation. + </para> + </listitem> + </orderedlist> + </para> + </section> + <section> + <title>Datasource Configuration</title> + <para> + The JBoss Portal binary download that was extracted in + <xref linkend="install_binarydownload"/> + , contains pre-configured Datasource descriptors for the more popular + databases. Datasource descriptors are provided for the MySQL 4 and 5, + PostgreSQL, Microsoft SQL Server, and Oracle databases, and can be found in + the + <filename>setup</filename> + subdirectory where the JBoss Portal binary was extracted to: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/setup/dsfiles.png"/> + </imageobject> + </mediaobject> + <para> + Copy the Datasource descriptor that matches your database into the + <filename> + $JBOSS_HOME/server/ + <replaceable>configuration</replaceable> + /deploy/ + </filename> + directory, where + <replaceable>configuration</replaceable> + is either all, default, minimal, or production. For example, if you are using + the production configuration, copy the Datasource descriptor into the + <filename>$JBOSS_HOME/server/production/deploy/</filename> + directory. The production configuration only exists on JBoss EAP + installations, and not JBoss AS. + </para> + <para> + After the Datasource descriptor has been copied into the + <filename>deploy</filename> + directory, make sure the + <computeroutput>user-name</computeroutput> + , + <computeroutput>password</computeroutput> + , + <computeroutput>connection-url</computeroutput> + , and + <computeroutput>driver-class</computeroutput> + , are correct for your chosen database. Datasource descriptor files can be + deployed to test before being used in production. The following is an example + Datasource descriptor for a PostgreSQL database: + </para> + <programlisting role="XML"><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<datasources> + <local-tx-datasource> + <jndi-name>PortalDS</jndi-name> + <connection-url>jdbc:postgresql:jbossportal</connection-url> + <driver-class>org.postgresql.Driver</driver-class> + <user-name>portal</user-name> + <password>portalpassword</password> + </local-tx-datasource> +</datasources> + ]]></programlisting> + <para> + For further details about Datasource descriptors, please refer to the + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=CreateAJDBCDataSource&... + JBoss JDBC Datasource Wiki page + </ulink> + . + </para> + </section> + </section> + <section> + <title>Deploying JBoss Portal</title> + <para>To start JBoss EAP or JBoss AS and deploy JBoss Portal:</para> + <para> + <orderedlist> + <listitem> + <para> + <emphasis role="bold">Datasource descriptor:</emphasis> + if you have not done so already, change into the + <filename>setup</filename> + subdirectory where the JBoss Portal binary was extracted to. Copy the + correct Datasource descriptor file ( + <filename>*-ds.xml</filename> + ) you modified in the previous steps into the + <filename> + $JBOSS_HOME/server/ + <replaceable>configuration</replaceable> + /deploy/ + </filename> + directory. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Start the server:</emphasis> + change into the + <filename>$JBOSS_HOME/bin/</filename> + directory. On Windows, execute + <command>run.bat</command> + . On Linux, run the + <command>sh run.sh</command> + command. To specify a configuration to use, for example, the default + configuration, append the + <command>-c default</command> + option to the + <command>run.bat</command> + or + <command>sh run.sh</command> + commands. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Log in to JBoss Portal:</emphasis> + using a Web browser, navigate to + <ulink url="http://localhost:8080/portal"/> + to open the JBoss Portal homepage. Log in using one of the two default + accounts: username + <emphasis>user</emphasis> + , password + <emphasis>user</emphasis> + , or username + <emphasis>admin</emphasis> + , password + <emphasis>admin</emphasis> + . + </para> + </listitem> + </orderedlist> + </para> + <formalpara> + <title>SQL Errors</title> + <para> + Tables are automatically created the first time JBoss Portal starts. When + deployed for the first time, JBoss Portal checks for the existence of the + initial tables, which have not been created yet. This causes errors such as + the following, which can safely be ignored: + </para> + </formalpara> + <para> + <programlisting><![CDATA[ +WARN [JDBCExceptionReporter] SQL Error: -22, SQLState: S0002 +ERROR [JDBCExceptionReporter] Table not found in statement ... +WARN [JDBCExceptionReporter] SQL Error: 1146, SQLState: 42S02 +ERROR [JDBCExceptionReporter] Table 'jbossportal.jbp_cms_repositoryentry' doesn't exist +WARN [JDBCExceptionReporter] SQL Error: 1146, SQLState: 42S02 +ERROR [JDBCExceptionReporter] Table 'jbossportal.jbp_cms_version_refs' doesn't exist +]]></programlisting> + </para> + </section> + +</chapter> + <chapter id="configuration"> + <!-- <chapterinfo> + <author> + <firstname>Thomas</firstname> + <surname>Heute</surname> + </author> + <author> + <firstname>Roy</firstname> + <surname>Russo</surname> + </author> + </chapterinfo>--> + <title>Customizing your Installation</title> + <para> + This chapter describes how to customize the default installation. This includes the JBoss EAP or JBoss AS listening port, email and proxy settings, and database dialect settings. For further configuration details, refer to <xref linkend="portaldescriptors"/> and <xref linkend="troubleshooting"/>. + </para> + <section> + <title>Changing the Port</title> + <para> + It is common for web services to run on port 80. By default, JBoss EAP and JBoss AS use port 8080. If you can not use <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=UsingPortForwardingWit... forwarding</ulink>, it is recommended to change the port JBoss EAP or JBoss AS listens on. To change the default port, open the <filename>$JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xml</filename> file, and edit the <computeroutput>Connector port</computeroutput> value for the <computeroutput>jboss.web</computeroutput> service; however, this configuration only applies to Apache Tomcat: + </para> +<programlisting role="XML"> +&lt;Service name="jboss.web"&gt; +&lt;Connector port="8088" address="${jboss.bind.address}" +</programlisting> + <para> + This example changes the default port to port 8088. The JBoss EAP or JBoss AS server must be restarted before the new port settings take affect. + </para> + <para> + The default SSL port is 8843. To enable HTTPS support, refer to the <ulink url="http://docs.jboss.org/jbossas/jboss4guide/r4/html/ch9.chapt.htm... AS Guide</ulink>. For further information, refer to the <ulink url="http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html">... Tomcat SSL configuration how-to</ulink>. + </para> + <para> + Please refer to <xref linkend="wsrp-ports"/> to update the WSRP service after having changed the port. + </para> + <para> + <warning> + <title>Root User Privileges</title> + <para> + Linux operating systems require root user privileges to run a service on a port less than 1024. Starting JBoss EAP or JBoss AS on port 80 as a non-privileged user will not work. Running JBoss EAP or JBoss AS as the root user could lead to security breaches. + </para> + </warning> + </para> + </section> + <section id="configuration-contextroot"> + <title>Changing the Context Path</title> + <para>By default, the main JBoss Portal page is accessible by navigating to <emphasis>http://localhost:8080/portal/index.html</emphasis>. This +can be changed to a different path, for example, +<emphasis>http://localhost:8080/index.html</emphasis>. The context path can be changed when using the deployed <filename>jboss-portal.sar/</filename>, or before building from source. To change the context path when using the JBoss Portal binary package: +</para> +<para> + <orderedlist> + <listitem> + <para>Open the <emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/jboss-web.xml</emphasis> file. If this file does not exist, copy and save the following example: + </para> +<programlisting><![CDATA[ +<?xml version="1.0"?> +<jboss-web> + <security-domain>java:jaas/portal</security-domain> + <context-root>/portal</context-root> + <replication-config> + <replication-trigger>SET</replication-trigger> + </replication-config> + <resource-ref> + <res-ref-name>jdbc/PortalDS</res-ref-name> + <jndi-name>java:PortalDS</jndi-name> + </resource-ref> +</jboss-web>]]></programlisting> + </listitem> + <listitem> + <para>Edit the + <computeroutput>&lt;context-root&gt;</computeroutput> element with the desired context path: + </para> +<programlisting> +<![CDATA[<context-root>/testing</context-root>]]> +</programlisting> + <para> + Using this example, the main JBoss Portal page would be reached by navigating to <emphasis>http://localhost:8080/testing</emphasis>. + </para> + </listitem> + </orderedlist> + </para> + <para> + To change the context path when building from source: + </para> + <para> + <orderedlist> + <listitem> + <para> + Change into the directory where the <filename>JBoss Portal Source Code</filename> ZIP file was extracted to, or where the source from SVN was checked out to. Copy the <filename>build/etc/local.properties-example</filename> file and save it as <filename>build/local.properties</filename>. + </para> + </listitem> + <listitem> + <para> + Open the <filename>build/local.properties</filename> file and edit the <computeroutput>portal.web.context-root</computeroutput> option with the desired context path: + </para> +<programlisting> +# Context root for the portal main servlet +portal.web.context-root=/testing +</programlisting> + <para> + Using this example, the main JBoss Portal page would be reached by navigating to <emphasis>http://localhost:8080/testing</emphasis>. + </para> + </listitem> + <listitem> + + <para> + To clean the project, make sure you are connected to the Internet, and change into the <filename>build/</filename> directory. Run the <command>ant clean</command> command. + </para> + </listitem> + <listitem> + <para> + Rebuild and redeploy JBoss Portal. Refer to <xref linkend="install_source"/> for build instructions. + </para> + </listitem> + </orderedlist> +</para> +<section> + <title>Changing the context-root</title> + <para> + By default, Apache Tomcat holds on to the root context, <emphasis>/</emphasis>. You may need to remove the <filename>$JBOSS_HOME/server/default/deploy/jboss-web.deployer/ROOT.war/</filename> directory, + or add a <filename>jboss-web.xml</filename> file, which declares another + context-root other than <emphasis>/</emphasis>, under the <filename>$JBOSS_HOME/server/default/deploy/jboss-web.deployer/ROOT.war/WEB-INF/</filename> directory, for the above changes to take affect. The following is an example <filename>jboss-web.xml</filename> file, which changes the Apache Tomcat context path to <computeroutput>/tomcat-root</computeroutput>: + </para> +<programlisting role="XML"><![CDATA[ +<?xml version="1.0"?> +<jboss-web> + <context-root>/tomcat-root</context-root> +</jboss-web>]]></programlisting> +</section> + </section> + <section id="configuration-hibdialect"> + <title>Forcing the Database Dialect</title> + <para> + This sections describes how to override the Database (DB) dialect settings. Under most circumstances, the auto-detect feature works. If the Hibernate dialect is not working correctly, override the default behavior by following the instructions in this section. + </para> + <section> + <title>Database Dialect Settings for JBoss Portal</title> + <para> + All <filename>hibernate.cfg.xml</filename> files in all JBoss Portal modules you intend to use need to be modified. The <filename>hibernate.cfg.xml</filename> files are found in the <filename>jboss-portal.sar/<replaceable>module</replaceable>/conf/hibernate/<replaceable>directory</replaceable>/</filename> directory, where <replaceable>module</replaceable> is the module name, and <replaceable>directory</replaceable> is a directory that, depending on the module, may or may not exist. + </para> + <para> + To modify these files to force the DB dialect, un-comment the following line from each <filename>hibernate.cfg.xml</filename> file in each JBoss Portal module you intend to use, so that it looks like the following: + </para> +<programlisting role="XML"><![CDATA[ +<!-- Force the dialect instead of using autodetection --> +<property name="dialect">org.hibernate.dialect.PostgreSQLDialect</property> +]]></programlisting> + <para> + Note: this example is for a PostgreSQL database. If you use another database, you need to modify <computeroutput>org.hibernate.dialect.PostgreSQLDialect</computeroutput> to reflect the correct database. For a list of supported dialects, refer to the <ulink url="http://www.hibernate.org/hib_docs/v3/reference/en/html/session-... list on the Hibernate website</ulink>. + </para> + </section> + <section> + <title>DB Dialect Settings for the CMS Component</title> + <para> + To modify the DB dialect setting for the JBoss Portal CMS component: + </para> + <para> + <orderedlist> + <listitem> + <para> + Open the <filename>jboss-portal.sar/portal-cms.sar/conf/hibernate/cms/hibernate.cfg.xml</filename> file. + </para> + </listitem> + <listitem> + <para> + Un-comment the following line, so that it looks as follows: + +<programlisting><![CDATA[ +<!-- Force the dialect instead of using autodetection --> +<property name="dialect">org.hibernate.dialect.PostgreSQLDialect</property> +]]></programlisting> +</para> + </listitem> + </orderedlist> + </para> + <para> + Note: this example is for a PostgreSQL database. If you use another database, you need to modify <computeroutput>org.hibernate.dialect.PostgreSQLDialect</computeroutput> to reflect the correct database. For a list of supported dialects, refer to the <ulink url="http://www.hibernate.org/hib_docs/v3/reference/en/html/session-... list on the Hibernate website</ulink>. + </para> + </section> + </section> + <section id="emailConfiguration"> + <title>Configuring the Email Service</title> + <para> + If you have a standard setup and a mail server installed, the email service should work without any extra configuration. Most Linux distributions have a mail server installed by default. The email service, for example, can be used to verify a user's email address when a user subscribes, or for CMS workflow notifications. + </para> + <para> + The email service is configured using the <filename>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/META-INF/jboss-service.xml</filename> file. The following is an example of the section which is used to configure the email service: + </para> +<programlisting role="XML"><![CDATA[ +<mbean +code="org.jboss.portal.core.impl.mail.MailModuleImpl" +name="portal:service=Module,type=Mail" +xmbean-dd="" +xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> +<xmbean/> +<depends>jboss:service=Mail</depends> +<depends>portal:service=Module,type=IdentityServiceController</depends> +<attribute name="QueueCapacity">-1</attribute> +<attribute name="Gateway">localhost</attribute> +<attribute name="SmtpUser"></attribute> +<attribute name="SmtpPassword"></attribute> +<attribute name="JavaMailDebugEnabled">false</attribute> +<attribute name="SMTPConnectionTimeout">100000</attribute> +<attribute name="SMTPTimeout">10000</attribute> +<attribute name="JNDIName">java:portal/MailModule</attribute> +</mbean>]]> +</programlisting> + + <para> + A different SMTP server (other than localhost) can be configured, along with a SMTP username and an SMTP password. The following is an example configuration that uses the Gmail SMTP server: + </para> +<programlisting role="XML"><![CDATA[ +<mbean +code="org.jboss.portal.core.impl.mail.MailModuleImpl" +name="portal:service=Module,type=Mail" +xmbean-dd="" +xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> +<xmbean/> +<depends>jboss:service=Mail</depends> +<depends>portal:service=Module,type=IdentityServiceController</depends> +<attribute name="QueueCapacity">-1</attribute> +<attribute name="Gateway">smtp.gmail.com</attribute> +<attribute name=&quot;SmtpUser&quot;&gt;username(a)gmail.com&lt;/attribute&gt; +<attribute name="SmtpPassword">myPassword</attribute> +<attribute name="JavaMailDebugEnabled">false</attribute> +<attribute name="SMTPConnectionTimeout">100000</attribute> +<attribute name="SMTPTimeout">10000</attribute> +<attribute name="JNDIName">java:portal/MailModule</attribute> +</mbean>]]> +</programlisting> + <para> + Using this example, replace <computeroutput&gt;username(a)gmail.com&lt;/computeroutput&gt; and <computeroutput>myPassword</computeroutput> with your correct Gmail username and password. + </para> +</section> + <section> + <title>Configuring proxy settings</title> + <para>There are a couple of scenarios where you need your proxy to be correctly defined at the <trademark class="trade">JVM</trademark> level so that you can access documents from Internet. It could be to get the thirdparty libraries if you decided to build JBoss Portal from the sources, to access RSS feeds or weather information in the samples portlet we provide or for your own needs.</para> + <para>To configure the proxy settings, you need to know the proxy host and the port to use. Then, + add them when starting Java.</para> + <para>Usually setting up JAVA_OPTS environment variable to <literal>-Dhttp.proxyHost=YOUR_PROXY_HOST -Dhttp.proxyPort=YOUR_PROXY_PORT</literal> + is enough.</para> + </section> + <section> + <title>Disabling Dynamic Proxy Un-wrapping</title> + <para>JBoss Portal uses the JBoss Microkernel for the service infrastructure. The JBoss Microkernel provides injection of services into other services, otherwise known as wiring. Due to the Microkernel being <trademark class="trade">JMX</trademark> based, it is only possible to inject dynamic proxies that talk to the MBeanServer. The overhead at runtime is minimal since the Microkernel implementation is highly optimized; however, when it is used with Java 5, a noticeable bottleneck occurs due to the fact that the implementation of the JMX API classes, <emphasis>javax.management.*</emphasis>, provided by the Java Platform, perform synchronization. This does not occur under <trademark class="trade">JDK</trademark> 1.4, since those classes are implemented by JBoss MX. + </para> + <para> + JBoss Portal services use a special kind of Model MBean called <emphasis>JBossServiceModelMBean</emphasis>, which allows the un-wrapping of injected dynamic proxies, and replaces them with Plain Old Java Object (POJO) services. This removes the bottleneck when using Java 5, and also provides a performance boost on JDK 1.4. By default this feature is enabled, but it is possible to disable. To do this on Linux operating systems, change into the <filename>$JBOSS_HOME/bin/</filename> directory and run the following command: + </para> + <para> +<programlisting> +sh run.sh -Dportal.kernel.no_proxies=false +</programlisting> +</para> +<para> + On Windows, run the following command: +</para> +<para> +<programlisting> +run.bat -Dportal.kernel.no_proxies=false +</programlisting> +</para> + </section> +</chapter> + <chapter id="changelog"> + <!-- <chapterinfo> + <author> + <firstname>Thomas</firstname> + <surname>Heute</surname> + </author> + </chapterinfo>--> + <title>Upgrading JBoss Portal 2.6 to 2.7</title> + <para> + <warning> + <para> + Before performing any instructions or operations in this chapter, back up your database and the entire JBoss EAP or JBoss AS directory! + </para> + </warning> + </para> + <para> + JBoss Portal 2.7 compatibility with JBoss Portal 2.6 is very high. The main differences are the use of JSR-286 features to replace + JBoss Portal specific features. The database schema hasn't changed. + </para> + + <section id="manual_migration"> + <title>Usage of JBossActionRequest</title> + <para>Usage of JBossActionRequest is not available directly anymore. From now on it is only accessible if the + <emphasis>org.jboss.portlet.filter.JBossPortletFilter</emphasis> is applied on the portlet. + To do so, first you will need to change the <emphasis>portlet.xml</emphasis> descriptor in order to declare + the new portlet as a JSR-286 portlet so that the filter can be applied. For a portlet named <emphasis>MyFooPortlet</emphasis> + it would now look like this: + </para> +<programlisting role="XML"><![CDATA[ +<portlet-app + xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2... http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + version="2.0"> + + <filter> + <filter-name>JBoss Portlet Filter</filter-name> + <filter-class>org.jboss.portlet.filter.JBossPortletFilter</filter-class> + <lifecycle>ACTION_PHASE</lifecycle> + <lifecycle>RENDER_PHASE</lifecycle> + </filter> + + <filter-mapping> + <filter-name>JBoss Portlet Filter</filter-name> + <portlet-name>MyFooPortlet</portlet-name> + </filter-mapping> + + + <portlet> + <description>My foo portlet</description> + <portlet-name>MyFooPortlet</portlet-name> + ... + </portlet> +</portlet-app> + +]]></programlisting> + <para>By not adding this filter on a portlet using JBossActionRequest/JBossActionResponse, an error message such as: + <emphasis>The request isn't a JBossRenderRequest, you probably need to activate the JBoss Portlet Filter: org.jboss.portlet.filter.JBossPortletFilter on MyFooPortlet</emphasis> + </para> + </section> + +</chapter> + <chapter id="tutorials"> + <!-- <chapterinfo> + <author> + <firstname>Chris</firstname> + <surname>Laprun</surname> + </author> + <author> + <firstname>Thomas</firstname> + <surname>Heute</surname> + </author> + </chapterinfo>--> + <title>Portlet Primer</title> + <section id="portlet_primer"> + <title>JSR-168 and JSR-286 overview</title> + <para> + The Portlet Specifications aims at defining portlets that can be used by any + <ulink url="http://www.jcp.org/en/jsr/detail?id=168"> + JSR-168 (Portlet 1.0) + </ulink> + or + <ulink url="http://www.jcp.org/en/jsr/detail?id=286"> + JSR-286 (Portlet 2.0) + </ulink> + portlet container. Most Java EE portals include one, it is obviously the case for + JBoss Portal which includes the JBoss Portlet container supporting the two + versions. This chapter gives a brief overview of the Portlet Specifications but + portlet developers are strongly encouraged to read the + <ulink url="http://www.jcp.org/en/jsr/detail?id=286"> + JSR-286 Portlet Specification + </ulink> + . + </para> + <para> + JBoss Portal is fully JSR-286 compliant, which means any JSR-168 or JSR-286 + portlet behaves as it is mandated by the respective specifications inside the + portal. + </para> + <section> + <title>Portal Pages</title> + <para> + A portal can be seen as pages with different areas, and inside areas, + different windows, and each window having one portlet: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata fileref="images/tutorials/SpecPortalDef.png" format="PNG" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + </section> + <section> + <title>Rendering Modes</title> + <para> + A portlet can have different view modes. Three modes are defined by the + JSR-286 specification: + </para> + <para> + <itemizedlist> + <listitem> + <para> + <emphasis>view</emphasis> + - generates markup reflecting the current state of the portlet. + </para> + </listitem> + <listitem> + <para> + <emphasis>edit</emphasis> + - allows a user to customize the behavior of the portlet. + </para> + </listitem> + <listitem> + <para> + <emphasis>help</emphasis> + - provides information to the user as to how to use the portlet. + </para> + </listitem> + </itemizedlist> + </para> + </section> + <section> + <title>Window States</title> + <para> + Window states are an indicator of how much page real-estate a portlet consumes + on any given page. The three states defined by the JSR-168 specification are: + </para> + <para> + <itemizedlist> + <listitem> + <para> + <emphasis>normal</emphasis> + - a portlet shares this page with other portlets. + </para> + </listitem> + <listitem> + <para> + <emphasis>minimized</emphasis> + -a portlet may show very little information, or none at all. + </para> + </listitem> + <listitem> + <para> + <emphasis>maximized</emphasis> + - a portlet may be the only portlet displayed on this page. + </para> + </listitem> + </itemizedlist> + </para> + </section> + </section> + <section id="tutorials_tutorials"> + <title>Tutorials</title> + <para> + The tutorials contained in this chapter are targeted toward portlet developers. + Although they are a good starting and reference point, it is highly recommend + that portlet developers read and understand the + <ulink url="http://www.jcp.org/en/jsr/detail?id=286"> + JSR-286 Portlet Specification + </ulink> + . Feel free to use the + <ulink url="http://jboss.org/index.html?module=bb&amp;op=viewforum&... + JBoss Portal User Forums + </ulink> + for user-to-user help. + </para> + <section> + <title>Deploying your first Portlet</title> + <section> + <title>Introduction</title> + <para> + This section describes how to deploy a portlet in JBoss Portal. You will + find the + <emphasis>SimplestHelloWorld</emphasis> + portlet in the + <literal>examples</literal> + directory at the root of your JBoss Portal binary package. + </para> + </section> + <section> + <title>Compiling</title> + <para> + This example is using Maven to compile and build the web archive. If you + don't have Maven already installed, you will find a version for your + operating system + <ulink url="http://maven.apache.org/download.html">here</ulink> + </para> + <para> + To compile and package the application, go to the SimplestHelloWorld + directory and type + <literal>mvn package</literal> + . + </para> + <para> + Once successfully packaged, the result should be available in: + <literal>SimplestHelloWorld/target/SimplestHelloWorld-0.0.1.war</literal> + . Simply copy that file into + <literal>JBOSS_HOME/server/default/deploy</literal> + , then start JBoss Application Server if it was not already started. + </para> + <para> + You should now see a new page called + <literal>SimplestHelloWorld</literal> + , with a window inside containing the portlet instance we have created, as + seen below. + </para> + <para> + <mediaobject> + <imageobject> + <imagedata fileref="images/tutorials/first_portlet/deployed.png"/> + </imageobject> + </mediaobject> + + SimplestHelloWorldPortlet deployed on a new page. + + </para> + </section> + <section> + <title>Package Structure</title> + <para> + Now that we have seen how to deploy an existing web application, let's have + a look inside. + </para> + <para> + Like other Java Platform, Enterprise Edition (Java EE) applications, + portlets are packaged in WAR files. A typical portlet WAR file can include + servlets, resource bundles, images, HTML, + <trademark class="trade">JavaServer</trademark> + Pages ( + <trademark class="trade">JSP</trademark> + ), and other static or dynamic files. The following is an example of the + directory structure of the HelloWorldPortlet portlet: + </para> + <programlistingco> + <areaspec> + <area id="tutorials.simplest.javaclass" coords="9"/> + <area id="tutorials.simplest.defaultobject" coords="10"/> + <area id="tutorials.simplest.portletinstances" coords="11"/> + <area id="tutorials.simplest.portlet" coords="12"/> + <area id="tutorials.simplest.web" coords="13"/> + </areaspec> + <programlisting><![CDATA[|-- SimplestHelloWorld-0.0.1.war +| `-- WEB-INF +| |-- classes +| | `-- org +| | `-- jboss +| | `-- portal +| | `-- portlet +| | `-- samples +| | `-- SimplestHelloWorldPortlet.class +| |-- default-object.xml +| |-- portlet-instances.xml +| |-- portlet.xml +| `-- web.xml]]> + </programlisting> + <calloutlist> + <callout arearefs="tutorials.simplest.javaclass"> + <para> + The compiled Java class implementing + <emphasis>javax.portlet.Portlet</emphasis> + (through + <emphasis>javax.portlet.GenericPortlet</emphasis> + ) + </para> + </callout> + <callout arearefs="tutorials.simplest.defaultobject"> + <para> + <emphasis>default-object.xml</emphasis> + is an optional file, it is used to define the layout of the + portal. It can be used to define the different portals, pages and + windows. The same result can be obtained through the + administration portal. Note that the definition of the layout is + stored in database, this file is then used to populate the + database during deployment which can be very useful during + development. + </para> + </callout> + <callout arearefs="tutorials.simplest.portletinstances"> + <para> + <emphasis>portlet-instances.xml</emphasis> + is also optional, it allows to create a portlet instance from the + SimpleHelloWorld portlet definition. Creating instances can also + be done through the administration portal. Note that the + definition of instances is stored in database, this file is then + used to populate the database during deployment which can be very + useful during development. Having portlet-instances.xml and + default-object.xml included in this package ensures that the + portlet will appear directly on the portal by just deploying the + web application. + </para> + </callout> + <callout arearefs="tutorials.simplest.portlet"> + <para> + This is the mandatory descriptor files for portlets. It is used + during deployment.. + </para> + </callout> + <callout arearefs="tutorials.simplest.web"> + <para>This is the mandatory descriptor for web applications.</para> + </callout> + </calloutlist> + </programlistingco> + </section> + + <section> + <title>Portlet Class</title> + <para>Let us study the Java class in detail.</para> + <para> + The following file is the + <filename> + SimplestHelloWorldPortlet/src/main/java/org/jboss/portal/portlet/samples/SimplestHelloWorldPortlet.java + </filename> + Java source. + </para> + <programlistingco> + <areaspec> + <area id="tutorials.simplest.extends" coords="10"/> + <area id="tutorials.simplest.doview" coords="13"/> + <area id="tutorials.simplest.writer" coords="15"/> + <area id="tutorials.simplest.write" coords="16"/> + <area id="tutorials.simplest.close" coords="17"/> + </areaspec> + <programlisting role="JAVA"><![CDATA[package org.jboss.portal.portlet.samples; + +import java.io.IOException; +import java.io.PrintWriter; + +import javax.portlet.GenericPortlet; +import javax.portlet.RenderRequest; +import javax.portlet.RenderResponse; + +public class SimplestHelloWorldPortlet extends GenericPortlet +{ + public void doView(RenderRequest request, + RenderResponse response) throws IOException + { + PrintWriter writer = response.getWriter(); + writer.write("Hello World !"); + writer.close(); + } +}]]> + </programlisting> + <calloutlist> + <callout arearefs="tutorials.simplest.extends"> + <para> + All portlets must implement the + <literal>javax.portlet.Portlet</literal> + interface. The portlet API provides a convenient implementation of + this interface, in the form of the + <literal>javax.portlet.GenericPortlet</literal> + class, which among other things, implements the + <literal>Portlet render</literal> + method to dispatch to abstract mode-specific methods to make it + easier to support the standard portlet modes. As well, it provides + a default implementation for the + <literal>processAction</literal> + , + <literal>init</literal> + and + <literal>destroy</literal> + methods. It is recommended to extend + <literal>GenericPortlet</literal> + for most cases. + </para> + </callout> + <callout arearefs="tutorials.simplest.doview"> + <para> + As we extend from + <literal>GenericPortlet</literal> + , and are only interested in supporting the + <literal>view</literal> + mode, only the + <literal>doView</literal> + method needs to be implemented, and the + <literal>GenericPortlet</literal> + <literal>render</literal> + implemention calls our implementation when the + <literal>view</literal> + mode is requested. + </para> + </callout> + <callout arearefs="tutorials.simplest.writer"> + <para> + Use the + <emphasis>RenderResponse</emphasis> + to obtain a writer to be used to produce content. + </para> + </callout> + <callout arearefs="tutorials.simplest.write"> + <para>Write the markup to display.</para> + </callout> + <callout arearefs="tutorials.simplest.close"> + <para>Closing the writer.</para> + </callout> + </calloutlist> + </programlistingco> + <para> + <note> + <title>Markup Fragments</title> + <para> + Portlets are responsible for generating markup fragments, as they are + included on a page and are surrounded by other portlets. In + particular, this means that a portlet outputting HTML must not output + any markup that cannot be found in a + <literal>&lt;body&gt;</literal> + element. + </para> + </note> + </para> + </section> + <section id="first_portlet_descriptors"> + <title>Application Descriptors</title> + <para> + JBoss Portal requires certain descriptors to be included in a portlet WAR + file. Some of these descriptors are defined by the Portlet Specification, + and others are specific to JBoss Portal. + </para> + <para> + The following is an example of the + <filename>SimplestHelloWorldPortlet/WEB-INF/portlet.xml</filename> + file. This file must adhere to its definition in the JSR-286 Portlet + Specification. You may define more than one portlet application in this + file: + </para> + <programlistingco> + <areaspec> + <area id="tutorials.simplest.portletname" coords="8"/> + <area id="tutorials.simplest.portletclass" coords="9"/> + <area id="tutorials.simplest.supports" coords="12"/> + <area id="tutorials.simplest.portletinfo" coords="15"/> + </areaspec> + <programlisting><![CDATA[ +<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2... + http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + version="2.0"> + <portlet> + <portlet-name>SimplestHelloWorldPortlet</portlet-name> + <portlet-class> + org.jboss.portal.portlet.samples.SimplestHelloWorldPortlet + </portlet-class> + <supports> + <mime-type>text/html</mime-type> + </supports> + <portlet-info> + <title>Simplest Hello World Portlet</title> + </portlet-info> + </portlet> +</portlet-app>]]> + </programlisting> + <calloutlist> + <callout arearefs="tutorials.simplest.portletname"> + <para> + Define the portlet name. It does not have to be the class name. + </para> + </callout> + <callout arearefs="tutorials.simplest.portletclass"> + <para> + The Fully Qualified Name (FQN) of your portlet class must be + declared here. + </para> + </callout> + <callout arearefs="tutorials.simplest.supports"> + <para> + The + <computeroutput>&lt;supports&gt;</computeroutput> + element declares all of the markup types that a portlet supports + in the + <literal>render</literal> + method. This is accomplished via the + <computeroutput>&lt;mime-type&gt;</computeroutput> + element, which is required for every portlet. The declared MIME + types must match the capability of the portlet. As well, it allows + you to pair which modes and window states are supported for each + markup type. All portlets must support the + <computeroutput>view</computeroutput> + portlet mode, so this does not have to be declared. Use the + <computeroutput>&lt;mime-type&gt;</computeroutput> + element to define which markup type your portlet supports, which + in this example, is + <computeroutput>text/html</computeroutput> + . This section tells the portal that it only outputs HTML. + </para> + </callout> + <callout arearefs="tutorials.simplest.portletinfo"> + <para> + When rendered, the portlet's title is displayed as the header in + the portlet window, unless it is overridden programmatically. In + this example, the title would be + <computeroutput>Simplest Hello World Portlet</computeroutput> + . + </para> + </callout> + </calloutlist> + </programlistingco> + <para> + The + <filename> + SimplestHelloWorldPortlet/WEB-INF/portlet-instances.xml + </filename> + file is a JBoss Portal specific descriptor, that allows you to create + instances of portlets. The + <computeroutput>&lt;portlet-ref&gt;</computeroutput> + value must match the + <computeroutput>&lt;portlet-name&gt;</computeroutput> + value given in the + <filename>SimplestHelloWorldPortlet/WEB-INF/portlet.xml</filename> + file. The + <computeroutput>&lt;instance-id&gt;</computeroutput> + value can be named anything, but it must match the + <computeroutput>&lt;instance-ref&gt;</computeroutput> + value given in the + <filename>*-object.xml</filename> + file, which in this example, would be the + <filename>SimplestHelloWorldPortlet/WEB-INF/default-object.xml</filename> + file. + </para> + <para> + The following is an example of the + <filename> + SimplestHelloWorldPortlet/WEB-INF/portlet-instances.xml + </filename> + file: + </para> + <programlisting role="XML"><![CDATA[<?xml version="1.0" standalone="yes"?> +<!DOCTYPE deployments PUBLIC + "-//JBoss Portal//DTD Portlet Instances 2.6//EN" + "http://www.jboss.org/portlet/dtd/portlet-instances_2_6.dtd"> +<deployments> + <deployment> + <instance> + <instance-id>SimplestHelloWorldInstance</instance-id> + <portlet-ref>SimplestHelloWorldPortlet</portlet-ref> + </instance> + </deployment> +</deployments>]]> + </programlisting> + <para> + The + <filename>*-object.xml</filename> + file is a JBoss Portal specific descriptor that allow users to define the + structure of their portal instances, and create and configure their windows + and pages. In the following example: + </para> + <para> + <itemizedlist> + <listitem> + <para>a portlet window is created.</para> + </listitem> + <listitem> + <para> + specifies that the window displays the markup generated by the + <computeroutput>SimplestHelloWorldInstance</computeroutput> + portlet instance. + </para> + </listitem> + <listitem> + <para> + the window is assigned to the page that we are creating and called + <computeroutput>SimplestHelloWorld</computeroutput> + page. + </para> + </listitem> + <listitem> + <para> + the + <computeroutput>&lt;region&gt;</computeroutput> + element specifies where the window appears on the page. + </para> + </listitem> + </itemizedlist> + </para> + <para> + The following is an example + <filename>SimplestHelloWorldPortlet/WEB-INF/default-object.xml</filename> + file: + </para> + <programlistingco> + <areaspec> + <area id="tutorials.simplest.parentref" coords="7"/> + <area id="tutorials.simplest.ifexists" coords="8"/> + <area id="tutorials.simplest.pagename" coords="12"/> + <area id="tutorials.simplest.windowname" coords="12"/> + <area id="tutorials.simplest.instanceref" coords="13"/> + <area id="tutorials.simplest.region" coords="14"/> + <area id="tutorials.simplest.height" coords="15"/> + </areaspec> + <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE deployments PUBLIC + "-//JBoss Portal//DTD Portal Object 2.6//EN" + "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd"> +<deployments> + <deployment> + <parent-ref>default</parent-ref> + <if-exists>overwrite</if-exists> + <page> + <page-name>SimplestHelloWorld</page-name> + <window> + <window-name>SimplestHelloWorldWindow</window-name> + <instance-ref>SimplestHelloWorldInstance</instance-ref> + <region>center</region> + <height>0</height> + </window> + </page> + </deployment> +</deployments>]]> + </programlisting> + <calloutlist> + <callout arearefs="tutorials.simplest.parentref"> + <para> + Tells the portal where this portlet appears. In this case, + <computeroutput>default.default</computeroutput> + specifies that the portlet appears in the portal instance named + <computeroutput>default</computeroutput> + , and on the page named + <computeroutput>default</computeroutput> + . + </para> + </callout> + <callout arearefs="tutorials.simplest.ifexists"> + <para> + Instructs the portal to overwrite or keep this object if it + already exists. Accepted values are + <computeroutput>overwrite</computeroutput> + and + <computeroutput>keep</computeroutput> + . The + <computeroutput>overwrite</computeroutput> + option destroys the existing object, and creates a new one based + on the content of the deployment. The + <computeroutput>keep</computeroutput> + option maintains the existing object deployment, or creates a new + one if it does not exist. + </para> + </callout> + <callout arearefs="tutorials.simplest.pagename"> + <para> + Here we are creating a new page to put the new window on. We give + that new page a name that will be by default used on the tab of + the default theme. + </para> + </callout> + <callout arearefs="tutorials.simplest.windowname"> + <para> + A + <emphasis role="bold">unique name</emphasis> + given to the portlet window. This can be named anything. + </para> + </callout> + <callout arearefs="tutorials.simplest.instanceref"> + <para> + The value of + <computeroutput>&lt;instance-ref&gt;</computeroutput> + must match the value of one of the + <computeroutput>&lt;instance-id&gt;</computeroutput> + elements found in the + <filename> + HelloWorldPortlet/WEB-INF/portlet-instances.xml + </filename> + file. + </para> + </callout> + <callout arearefs="tutorials.simplest.region"> + <para> + Specifies where the window appears within the page layout. + </para> + </callout> + <callout arearefs="tutorials.simplest.height"> + <para> + Specifies where the window appears within the page layout. + </para> + </callout> + </calloutlist> + </programlistingco> + <para> + The following diagram illustrates the relationship between the + <filename>portlet.xml</filename> + , + <filename>portlet-instances.xml</filename> + , and + <filename>default-object.xml</filename> + descriptors: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata fileref="images/tutorials/first_portlet/desc_relationship.png" align="center" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + + <para> + JBoss Portal 2.6 introduced the notion of + <emphasis>content-type</emphasis> + , which is a generic mechanism to specify what content displayed by a given + portlet window. The + <computeroutput>window</computeroutput> + section of the previous example, + <filename>SimplestHelloWorldPortlet/WEB-INF/default-object.xml</filename> + , can be re-written to take advantage of the new content framework. The + following is an example deployment descriptor that uses the new content + framework: + </para> + <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE deployments PUBLIC + "-//JBoss Portal//DTD Portal Object 2.6//EN" + "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd"> +<deployments> + <deployment> + <parent-ref>default.default</parent-ref> + <if-exists>overwrite</if-exists> + <window> + <window-name>SimplestHelloWorldWindow</window-name> + <content> + <content-type>portlet</content-type> + <content-uri>SimplestHelloWorldInstance</content-uri> + </content> + <region>center</region> + <height>1</height> + </window> + </deployment> +</deployments>]]> + </programlisting> + <para> + + This declaration is equivalent to the previous + <filename>SimplestHelloWorldPortlet/WEB-INF/default-object.xml</filename> + example. Use + <computeroutput>&lt;content-type&gt;</computeroutput> + to specify the content to display. In this example, the content being + displayed by the + <computeroutput>SimplestHelloWorldWindow</computeroutput> + is a + <computeroutput>portlet</computeroutput> + . The + <computeroutput>&lt;content-uri&gt;</computeroutput> + element specifies which content to display, which in this example, is the + <computeroutput>SimplestHelloWorldInstance</computeroutput> + : + </para> + <programlisting role="XML"><![CDATA[<content> + <content-type>portlet</content-type> + <content-uri>SimplestHelloWorldInstance</content-uri> +</content>]]> + </programlisting> + <para> + To display certain content or a file, use the + <computeroutput>cms</computeroutput> + content-type, with the + <computeroutput>&lt;content-uri&gt;</computeroutput> + element being the path to the file in the CMS. This behavior is pluggable: + you can plug in almost any type of content. + </para> + <formalpara> + <title>Beware of context-path change</title> + <para> + If the context-path change the portal may not be able to find a + reference on your portlets anymore. For that reason it's recommended to + add the following descriptor + <filename>WEB-INF/jboss-portlet.xml</filename> + which is not mandatory: + </para> + </formalpara> +<programlisting role="XML"><![CDATA[ +<!DOCTYPE portlet-app PUBLIC + "-//JBoss Portal//DTD JBoss Portlet 2.6//EN" + "http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd"> + +<portlet-app> + <app-id>SimplestHelloWorld</app-id> +</portlet-app>]]></programlisting> + </section> + </section> + <section> + <title> + <trademark class="trade">JavaServer</trademark> + Pages Portlet Example + </title> + <section> + <title>Introduction</title> + <para> + Now we will add more features to the previous example and also use a JSP + page to render the markup. We will use the portlet tag library to generate + links to our portlet in different ways and use the other standard portlet + modes. This example can be found in the directory + <literal>JSPHelloUser</literal>. + Use <literal>mvn package</literal> then copy <filename>JSPHelloUser/target/JSPHelloUser-0.0.1.war</filename> + in the <literal>deploy</literal> directory of JBoss Application Server. + Point your brwoser to <literal/>, you should see the following: + <mediaobject> + <imageobject> + <imagedata fileref="images/tutorials/jsp_portlet/output.png" align="center" scalefit="1"/> + </imageobject> + </mediaobject> + <note> + <para>The <literal>EDIT</literal> button only appears with logged-in users, which is not the case + on the screenshot</para> + </note> + </para> + </section> + <section> + <title>Package Structure</title> + <para> + The structure doesn't change much at the exception of adding some JSP files + detailed later. + </para> + <para> + The JSPHelloUser portlet contains the traditional portlet and JBoss Portal + specific application descriptors. The following is an example of the + directory structure of the JSPHelloUser portlet: + </para> + <programlisting><![CDATA[JSPHelloUser-0.0.1.war + |-- META-INF + | |-- MANIFEST.MF + | `-- maven + | `-- org.jboss.portal.example + | `-- JSPHelloUser + | |-- pom.properties + | `-- pom.xml + |-- WEB-INF + | |-- classes + | | `-- org + | | `-- jboss + | | `-- portal + | | `-- portlet + | | `-- samples + | | `-- JSPHelloUserPortlet.class + | |-- default-object.xml + | |-- jboss-portlet.xml + | |-- portlet-instances.xml + | |-- portlet.xml + | `-- web.xml + `-- jsp + |-- edit.jsp + |-- hello.jsp + |-- help.jsp + `-- welcome.jsp]]> + </programlisting> + </section> + <section> + <title>Portlet Class</title> + <para>Let's study the Java class in detail.</para> + <para> + The following file is the + <filename> + JSPHelloUser/src/main/java/org/jboss/portal/portlet/samples/JSPHelloUserPortlet.java + </filename> + Java source. It is split in different pieces. + </para> + <programlistingco> + <areaspec> + <area id="tutorials.jsphello.doView" coords="18"/> + <area id="tutorials.jsphello.renderParameter" coords="21"/> + <area id="tutorials.jsphello.requestDispatcher" coords="25"/> + <area id="tutorials.jsphello.include" coords="26"/> + </areaspec> + <programlisting role="JAVA"><![CDATA[package org.jboss.portal.portlet.samples; +package org.jboss.portal.portlet.samples; + +import java.io.IOException; + +import javax.portlet.ActionRequest; +import javax.portlet.ActionResponse; +import javax.portlet.GenericPortlet; +import javax.portlet.PortletException; +import javax.portlet.PortletRequestDispatcher; +import javax.portlet.RenderRequest; +import javax.portlet.RenderResponse; +import javax.portlet.UnavailableException; + +public class JSPHelloUserPortlet extends GenericPortlet +{ + + public void doView(RenderRequest request, RenderResponse response) + throws PortletException, IOException + { + String sYourName = (String) request.getParameter("yourname"); + if (sYourName != null) + { + request.setAttribute("yourname", sYourName); + PortletRequestDispatcher prd = + getPortletContext().getRequestDispatcher("/jsp/hello.jsp"); + prd.include(request, response); + } + else + { + PortletRequestDispatcher prd = getPortletContext().getRequestDispatcher("/jsp/welcome.jsp"); + prd.include(request, response); + } + } +...]]></programlisting> + <calloutlist> + <callout arearefs="tutorials.jsphello.doView"> + <para> + As in the first portlet, we override the + <emphasis>doView</emphasis> + method. + </para> + </callout> + <callout arearefs="tutorials.jsphello.renderParameter"> + <para> + Here we try to obtain the value of the render parameter names + <literal>yourname</literal> + . If defined we want to redirect to the + <filename>hello.jsp</filename> + JSP page, otherwise to the + <filename>welcome.jsp</filename> + JSP page. + </para> + </callout> + <callout arearefs="tutorials.jsphello.requestDispatcher"> + <para> + Very similar to the Servlet way, we get a request dispatcher on a + file located within the web archive. + </para> + </callout> + <callout arearefs="tutorials.jsphello.include"> + <para> + The last step is to perform the inclusion of the markup obtained + from the JSP. + </para> + </callout> + </calloutlist> + </programlistingco> + <para> + We have seen the + <literal>VIEW</literal> + portlet mode, the spec defines two other modes that can be used called + <literal>EDIT</literal> + and + <literal>HELP</literal> + . In order to enable those modes, they will need to be defined in the + <filename>portlet.xml</filename> + descriptor as we will see later. Having those modes defined will enable the + corresponding buttons on the portlet's window. + </para> + <para> + The generic portlet that is inherited dispatches the different views to + methods named: + <literal>doView</literal> + , + <literal>doHelp</literal> + and + <literal>doEdit</literal> + . Let's watch the code for those two last portlet modes. + </para> + <programlisting role="JAVA"><![CDATA[... + protected void doHelp(RenderRequest rRequest, RenderResponse rResponse) throws PortletException, IOException, + UnavailableException + { + rResponse.setContentType("text/html"); + PortletRequestDispatcher prd = getPortletContext().getRequestDispatcher("/jsp/help.jsp"); + prd.include(rRequest, rResponse); + } + + protected void doEdit(RenderRequest rRequest, RenderResponse rResponse) throws PortletException, IOException, + UnavailableException + { + rResponse.setContentType("text/html"); + PortletRequestDispatcher prd = getPortletContext().getRequestDispatcher("/jsp/edit.jsp"); + prd.include(rRequest, rResponse); + } +...]]></programlisting> + + <para> + If you have read the portlet specification carefully you should have notice + that portlet calls happen in one or two phases. One when the portlet is + just rendered, two when the portlet is actionned then rendered. An action + phase is a phase where some state change. The render phase will have access + to render parameters that will be passed each time the portlet is refreshed + (with the exception of caching capabilities). + </para> + <para> + The code to be executed during an action has to be implemented in the + <emphasis>processAction</emphasis> + method of the portlet. + </para> + <programlistingco> + <areaspec> + <area id="tutorials.jsphello.processAction" coords="2"/> + <area id="tutorials.jsphello.getActionParameter" coords="5"/> + <area id="tutorials.jsphello.setRenderParameter" coords="6"/> + </areaspec> + <programlisting role="JAVA"><![CDATA[... + public void processAction(ActionRequest aRequest, ActionResponse aResponse) throws PortletException, IOException, + UnavailableException + { + String sYourname = (String) aRequest.getParameter("yourname"); + aResponse.setRenderParameter("yourname", sYourname); + } +...]]></programlisting> + <calloutlist> + <callout arearefs="tutorials.jsphello.processAction"> + <para> + <literal>processAction</literal> + is the method from GernericPorlet to override for the + <emphasis>action</emphasis> + phase. + </para> + </callout> + <callout arearefs="tutorials.jsphello.getActionParameter"> + <para> + Here we retrieve the parameter obtained through an + <emphasis>action URL</emphasis> + . + </para> + </callout> + <callout arearefs="tutorials.jsphello.setRenderParameter"> + <para> + Here we need to keep the value of + <literal>yourname</literal> + to make it available in the rendering phase. With the previous + line, we are simply copying an action parameter to a render + parameter for the sake of this example. + </para> + </callout> + </calloutlist> + </programlistingco> + </section> + <section> + <title> + <trademark class="trade">JSP</trademark> + files and the Portlet Tag Library + </title> + <para>Let's have a look inside the JSP pages.</para> + <para> + The + <filename>help.jsp</filename> + and + <filename>edit.jsp</filename> + files are very simple, they simply display some text. Note that we used CSS + styles as defined in the portlet specification. It ensures that the portlet + will look "good" within the theme and accross portal vendors. + </para> + <programlisting role="XHTML"><![CDATA[<div class="portlet-section-header">Help mode</div> +<div class="portlet-section-body">This is the help mode, a convenient place to give the user some help information.</div>]]></programlisting> + <programlisting role="XHTML"><![CDATA[<div class="portlet-section-header">Edit mode</div> +<div class="portlet-section-body">This is the edit mode, a convenient place to let the user change his portlet preferences.</div>]]></programlisting> + <para> + Now let's have a look at the landing page, it contains the links and form + to call our portlet: + </para> + <programlistingco> + <areaspec> + <area id="tutorials.jsphello.taglib" coords="1"/> + <area id="tutorials.jsphello.method1" coords="13"/> + <area id="tutorials.jsphello.method2.1" coords="20"/> + <area id="tutorials.jsphello.method2.2" coords="24"/> + <area id="tutorials.jsphello.method3.1" coords="30"/> + <area id="tutorials.jsphello.method3.2" coords="31"/> + </areaspec> + + <programlisting><![CDATA[<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %> + +<div class="portlet-section-header">Welcome !</div> + +<br/> + +<div class="portlet-font">Welcome on the JSP Hello User portlet, +my name is JBoss Portal. What's yours ?</div> + +<br/> + +<div class="portlet-font">Method 1: We simply pass the parameter to the render phase:<br/> +<a href="<portlet:renderURL><portlet:param name="yourname" value="John Doe"/> + </portlet:renderURL>">John Doe</a></div> + +<br/> + +<div class="portlet-font">Method 2: We pass the parameter to the render phase, using valid XML: +Please check the source code to see the difference with Method 1. +<portlet:renderURL var="myRenderURL"> + <portlet:param name="yourname" value='John Doe'/> +</portlet:renderURL> +<br/> +<a href="<%= myRenderURL %>">John Doe</a></div> + +<br/> + +<div class="portlet-font">Method 3: We use a form:<br/> + +<portlet:actionURL var="myActionURL"/> +<form action="<%= myActionURL %>" method="POST"> + <span class="portlet-form-field-label">Name:</span> + <input class="portlet-form-input-field" type="text" name="yourname"/> + <input class="portlet-form-button" type="Submit"/> +</form> +</div>]]></programlisting> + <calloutlist> + <callout arearefs="tutorials.jsphello.taglib"> + <para> + Since we will use the portlet taglib, we first need to declare it. + </para> + </callout> + <callout arearefs="tutorials.jsphello.method1"> + <para> + The first method showed here is the simplest one, + <literal>portlet:renderURL</literal> + will create a URL that will call the render phase of the current + portlet and append the result at the place of the markup (Here + within a tag...). We also added a parameter directly on the URL. + </para> + </callout> + <callout arearefs="tutorials.jsphello.method2.1"> + <para> + In this method instead of having a tag within another tag, which + is not XML valid, we use the + <literal>var</literal> + attribute. Instead of printing the url the + <literal>portlet:renderURL</literal> + tag will store the result in the referenced variable ( + <literal>myRenderURL</literal> + in our case). + </para> + </callout> + <callout arearefs="tutorials.jsphello.method2.2"> + <para> + The variable + <literal>myRenderURL</literal> + is used like any other JSP variable. + </para> + </callout> + <callout arearefs="tutorials.jsphello.method3.1"> + <para> + The third method mixes form submission and action request. Like in + the second method, we used a temporary variable to put the created + URL into. + </para> + </callout> + <callout arearefs="tutorials.jsphello.method3.2"> + <para>The action URL is used in the HTML form.</para> + </callout> + </calloutlist> + </programlistingco> + + <para> + On the third method, first the action phase is triggered then later in the request, the render + phase is triggered, which output some content back to the web browser based on the + available render parameters. + <mediaobject> + <imageobject> + <imagedata format="PNG" fileref="images/tutorials/jsp_portlet/process.png" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + </section> + <section> + <title> + <trademark class="trade">JSF</trademark> + example using the JBoss Portlet Bridge + </title> + <para>In order to write a portlet using JSF we need a piece of software called 'bridge' that + lets us write a portlet application as if it was a JSF application, the bridge takes care of the + interactions between the two layers.</para> + <para>Such an example is available in examples/JSFHelloUser, it uses the JBoss Portlet Bridge. + The configuration is slightly different from a JSP application, since it is a bit tricky it is usally a good + idea to copy an existing application that starting from scratch.</para> + <para>First, as any JSF application, the file <literal>faces-config.xml</literal> is required. It includes + the following required information in it: + <programlisting role="XML"><![CDATA[<faces-config> +... + <application> + <view-handler>org.jboss.portletbridge.application.PortletViewHandler</view-handler> + <state-manager>org.jboss.portletbridge.application.PortletStateManager</state-manager> + </application> +... +</faces-config> ]]></programlisting> + The portlet bridge libraries must be available and are usually bundled with the <literal>WEB-INF/lib</literal> + directory of the web archive.</para> + <para>The other difference compare to a regular portlet application, can be found in the portlet + descriptor. All details about it can be found in the JSR-301 specification that the JBoss Portlet Bridge + implements. + <programlistingco> + <areaspec> + <area id="tutorials.jsf.portlet" coords="9"/> + <area id="tutorials.jsf.view" coords="21"/> + <area id="tutorials.jsf.edit" coords="26"/> + <area id="tutorials.jsf.help" coords="31"/> + </areaspec> + <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2... + http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + version="2.0"> + <portlet> + <portlet-name>JSFHelloUserPortlet</portlet-name> + <portlet-class>javax.portlet.faces.GenericFacesPortlet</portlet-class> + <supports> + <mime-type>text/html</mime-type> + <portlet-mode>view</portlet-mode> + <portlet-mode>edit</portlet-mode> + <portlet-mode>help</portlet-mode> + </supports> + <portlet-info> + <title>JSF Hello User Portlet</title> + </portlet-info> + + <init-param> + <name>javax.portlet.faces.defaultViewId.view</name> + <value>/jsf/welcome.jsp</value> + </init-param> + + <init-param> + <name>javax.portlet.faces.defaultViewId.edit</name> + <value>/jsf/edit.jsp</value> + </init-param> + + <init-param> + <name>javax.portlet.faces.defaultViewId.help</name> + <value>/jsf/help.jsp</value> + </init-param> + + </portlet> +</portlet-app>]]></programlisting> + <calloutlist> + <callout arearefs="tutorials.jsf.portlet"><para>All JSF portlets define <literal>javax.portlet.faces.GenericFacesPortlet</literal> + as portlet class. This class is part of the JBoss Portlet Bridge</para></callout> + <callout arearefs="tutorials.jsf.view"><para>This is a mandatory parameter to define what's the default page to display.</para></callout> + <callout arearefs="tutorials.jsf.edit"><para>This parameter defines which page to display on the 'edit' mode.</para></callout> + <callout arearefs="tutorials.jsf.help"><para>This parameter defines which page to display on the 'help' mode.</para></callout> + </calloutlist> + </programlistingco> + </para> + </section> + </section> + </section> +</chapter> + <chapter id="xmldescriptors"> + <!-- <chapterinfo> + <author> + <firstname>Thomas</firstname> + <surname>Heute</surname> + </author> + <author> + <firstname>Roy</firstname> + <surname>Russo</surname> + </author> + </chapterinfo>--> + <title>XML Descriptors</title> + <section> + <title>DTDs</title> + <para> + To use a DTD, add the following declaration to the start of the desired descriptors: + </para> +<programlisting role="XML"><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE deployments PUBLIC +"-//JBoss Portal//DTD Portal Object 2.6//EN" +"http://www.jboss.org/portal/dtd/portal-object_2_6.dtd">]]> +</programlisting> + <para> + If you do not use the DTD declaration, the previous mechanism for XML validation is used. The DTD is more strict, specifically with the order of XML elements. The following is an example from a <filename>*-object.xml</filename> descriptor, which is valid if you are not using the DTD, but is rejected if you are: + </para> + <programlisting role="XML"><![CDATA[ +<if-exists>overwrite</if-exists> +<parent-ref>default.default</parent-ref>]]> +</programlisting> + <para> + The correct element order, and one which is valid against the DTD, is as follows: + </para> +<programlisting role="XML"><![CDATA[ +<parent-ref>default.default</parent-ref> +<if-exists>overwrite</if-exists>]]> +</programlisting> + <para> + The following DTDs are available: + </para> + <para> + <itemizedlist> + <listitem> + <para> + for <filename>-object.xml</filename> descriptors: <userinput>"-//JBoss Portal//DTD Portal Object 2.6//EN"</userinput> + </para> + </listitem> + <listitem> + <para> + for <filename>jboss-app.xml</filename> descriptors: <userinput>"-//JBoss Portal//DTD JBoss Web Application 2.6//EN"</userinput> + </para> + </listitem> + <listitem> + <para> + for <filename>jboss-portlet.xml</filename> descriptors: <userinput>"-//JBoss Portal//DTD JBoss Portlet 2.6//EN"</userinput> + </para> + </listitem> + <listitem> + <para> + for <filename>portlet-instances.xml</filename> descriptors: <userinput>"-//JBoss Portal//DTD Portlet Instances 2.6//EN"</userinput> + </para> + </listitem> + </itemizedlist> +</para> +<para> + The DTDs are located in the <filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/jboss-portal.sar/dtd/</filename> directory. +</para> + <section> + <title>The JBoss Portlet DTD</title> + <para> + The following items refer to elements found in the JBoss Portlet DTD, <filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/jboss-portal.sar/dtd/jboss-portlet_<replaceable>version_number</replaceable>.dtd</filename>: + </para> +<programlisting><![CDATA[ +<!ELEMENT portlet-app (remotable?,portlet*,service*)>]]> +</programlisting> + <para> + Use the <computeroutput>&lt;remotable&gt;</computeroutput> element to configure the default behavior of portlets with respect to WSRP exposure: if no value is given, the value is either the value globally defined at the portlet application level, or <computeroutput>false</computeroutput>. Accepted values are <computeroutput>true</computeroutput> and <computeroutput>false</computeroutput>. + </para> + <para> + You can configure specific settings of the portlet container for each portlet defined in the <filename>WEB-INF/portlet.xml</filename> file. Use the <computeroutput>&lt;service&gt;</computeroutput> element to inject services into the portlet context of applications. + </para> +<programlisting><![CDATA[ +<!ELEMENT portlet (portlet-name,remotable?,ajax?,session-config?,transaction?, +header-content?,portlet-info?)>]]> +</programlisting> + <para> + Additional configuration of the portlet. The <computeroutput>&lt;portlet-name&gt;</computeroutput> element defines the portlet name. It must match a portlet defined in the <filename>WEB-INF/portlet.xml</filename> file for that application. + </para> + <para> + Use the <computeroutput>&lt;remotable&gt;</computeroutput> element to configure the default behavior of portlets with respect to WSRP exposure: if no value is given, the value is either the value globally defined at the portlet application level, or <computeroutput>false</computeroutput>. + </para> + <para> + The <computeroutput>&lt;trans-attribute&gt;</computeroutput> element specifies the behavior of the portlet when it is invoked at runtime with respect to the transactional context. Depending on how the portlet is + invoked, a transaction may or may not exist before the portlet is invoked. The portal transaction is usually present in the local context. The default value is <computeroutput>NotSupported</computeroutput>, which means that the portal transaction is suspended for the duration of the portlet's invocation. Accepted values are <computeroutput>Required</computeroutput>, <computeroutput>Mandatory</computeroutput>, <computeroutput>Never</computeroutput>, <computeroutput>Supports</computeroutput>, <computeroutput>NotSupported</computeroutput>, and <computeroutput>RequiresNew</computeroutput>. + </para> + <para> + The following is an example section from a <filename>WEB-INF/portlet.xml</filename> file, which uses the <computeroutput>&lt;portlet-name&gt;</computeroutput>, <computeroutput>&lt;remotable&gt;</computeroutput>, and <computeroutput>&lt;trans-attribute&gt;</computeroutput> elements: + </para> +<programlisting role="XML"><![CDATA[ +<portlet> + <portlet-name>MyPortlet</portlet-name> + <remotable>true</remotable> + <trans-attribute>Required</trans-attribute> +</portlet>]]> +</programlisting> +<programlisting><![CDATA[ +<!ELEMENT portlet-name (#PCDATA)>]]> +</programlisting><para> + The portlet name. + </para> + <programlisting><![CDATA[ +<!ELEMENT remotable (#PCDATA)>]]> +</programlisting> + <para> + Accepted values are <computeroutput>true</computeroutput> and <computeroutput>false</computeroutput>. + </para> +<programlisting><![CDATA[ +<!ELEMENT ajax (partial-refresh)>]]> +</programlisting> + <para> + Use the <computeroutput>ajax</computeroutput> element to configure the Asynchronous JavaScript and XML (AJAX) capabilities of the portlet. + </para> +<programlisting><![CDATA[ +<!ELEMENT partial-refresh (#PCDATA)>]]> +</programlisting> + <para> + If a portlet uses the <computeroutput>true</computeroutput> value for the <computeroutput>&lt;partial-refresh&gt;</computeroutput> element, the portal uses partial-page refreshing and only renders that portlet. If the <computeroutput>&lt;partial-refresh&gt;</computeroutput> element uses a <computeroutput>false</computeroutput> value, the portal uses a full-page refresh when the portlet is refreshed. + </para> +<programlisting><![CDATA[ +<!ELEMENT session-config (distributed)>]]> +</programlisting> + <para> + The <computeroutput>&lt;session-config&gt;</computeroutput> element configures the portlet session for the portlet. The <computeroutput>&lt;distributed&gt;</computeroutput> element instructs the container to distribute the session attributes using portal session replication. This only applies to local portlets, not remote portlets. + </para> + <para> + The following is an example of the <computeroutput>&lt;session-config&gt;</computeroutput> and <computeroutput>&lt;distributed&gt;</computeroutput> elements: + </para> +<programlisting role="XML"><![CDATA[ +<session-config> + <distributed>true</distributed> +</session-config>]]> +</programlisting> +<programlisting><![CDATA[ +<!ELEMENT distributed (#PCDATA)>]]> +</programlisting> + <para> + Accepted values are <computeroutput>true</computeroutput> and <computeroutput>false</computeroutput>. The default value is <computeroutput>false</computeroutput>. + </para> +<programlisting><![CDATA[ +<!ELEMENT transaction (trans-attribute)>]]> +</programlisting> + <para> + The <computeroutput>&lt;transaction&gt;</computeroutput> element defines how the portlet behaves with regards to the transactional context. The <computeroutput>&lt;trans-attribute&gt;</computeroutput> element specifies the behavior of the portlet when it is invoked at runtime, with respect to the transactional context. Depending on how the portlet is invoked, a transaction may or may not exist before the portlet is invoked. The portal transaction is usually present in the local context. + </para> + <para> + The following is an example of the <computeroutput>&lt;transaction&gt;</computeroutput> and <computeroutput>&lt;trans-attribute&gt;</computeroutput> elements: + </para> +<programlisting role="XML"><![CDATA[ +<transaction> + <trans-attribute>Required</transaction> +<transaction>]]> +</programlisting> +<programlisting><![CDATA[ +<!ELEMENT trans-attribute (#PCDATA)>]]> +</programlisting> + <para> + The default value is <computeroutput>NotSupported</computeroutput>, which means that the portal transaction is suspended for the duration of the portlet's invocation. Accepted values are <computeroutput>Required</computeroutput>, <computeroutput>Mandatory</computeroutput>, <computeroutput>Never</computeroutput>, <computeroutput>Supports</computeroutput>, <computeroutput>NotSupported</computeroutput>, and <computeroutput>RequiresNew</computeroutput>. + </para> +<programlisting><![CDATA[ +<!ELEMENT header-content (link|script|meta)*>]]> +</programlisting> + <para> + Specify the content to be included in the portal aggregated page when the portlet is present on that page. This setting only applies when the portlet is used in the local mode. + </para> +<programlisting><![CDATA[ +<!ELEMENT link EMPTY>]]> +</programlisting> + <para> + No content is allowed inside a link element. + </para> +<programlisting><![CDATA[ +<!ELEMENT script (#PCDATA)>]]> +</programlisting> + <para> + Use the <computeroutput>&lt;script&gt;</computeroutput> element for inline script definitions. + </para> +<programlisting><![CDATA[ +<!ELEMENT meta EMPTY>]]> +</programlisting> + <para> + No content is allowed for the <computeroutput>&lt;meta&gt;</computeroutput> element. + </para> +<programlisting><![CDATA[ +<!ELEMENT service (service-name,service-class,service-ref)>]]> +</programlisting> + <para> + Declare a service that will be injected by the portlet container as an attribute of the portlet context. + </para> + <para> + The following is an example of the <computeroutput>&lt;service&gt;</computeroutput> element: + </para> +<programlisting role="XML"><![CDATA[ +<service> + <service-name>UserModule</service-name> + <service-class>org.jboss.portal.identity.UserModule</service-class> + <service-ref>:service=Module,type=User</service-ref> +</service>]]> +</programlisting> + <para> + To use an injected service in a portlet, perform a lookup of the <computeroutput>&lt;service-name&gt;</computeroutput>, for example, using the <computeroutput>init()</computeroutput> lifecycle method: + </para> +<programlisting role="JAVA"><![CDATA[ +public void init() +{ + UserModule userModule = (UserModule)getPortletContext().getAttribute("UserModule"); +}]]> +</programlisting> +<programlisting><![CDATA[ +<!ELEMENT service-name (#PCDATA)>]]> +</programlisting> + <para> + The <computeroutput>&lt;service-name&gt;</computeroutput> element defines the name that binds the service as a portlet context attribute. + </para> +<programlisting><![CDATA[ +<!ELEMENT service-class (#PCDATA)>]]> +</programlisting> + <para> + The <computeroutput>&lt;service-class&gt;</computeroutput> element defines the fully qualified name of the interface that the service implements. + </para> +<programlisting><![CDATA[ +<!ELEMENT service-ref (#PCDATA)>]]> +</programlisting> + <para> + The <computeroutput>&lt;service-ref&gt;</computeroutput> element defines the reference to the service. In the JMX Microkernel environment, this consist of the JMX name of the service MBean. For an MBean reference, if the domain is left out, the current domain of the portal is used. + </para> + </section> + <section> + <title>The JBoss Portlet Instance DTD</title> + <para> + The following items refer to elements found in the JBoss Portlet Instance DTD, <filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/jboss-portal.sar/dtd/portlet-instances_<replaceable>version_number</replaceable>.dtd</filename>: + </para> +<programlisting><![CDATA[ +<!ELEMENT deployments (deployment*)>]]> +</programlisting> + <para> + The <computeroutput>&lt;deployments&gt;</computeroutput> element is a container for <computeroutput>&lt;deployment&gt;</computeroutput> elements. + </para> +<programlisting><![CDATA[ +<!ELEMENT deployment (if-exists?,instance)>]]> +</programlisting> + <para> + The <computeroutput>&lt;deployment&gt;</computeroutput> element is a container for the <computeroutput>&lt;instance&gt;</computeroutput> element. + </para> +<programlisting><![CDATA[ +<!ELEMENT if-exists (#PCDATA)>]]> +</programlisting> + <para> + The <computeroutput>&lt;if-exists&gt;</computeroutput> element defines the action to take if an instance with the same name already exists. Accepted values are <computeroutput>overwrite</computeroutput> and <computeroutput>keep</computeroutput>. The <computeroutput>overwrite</computeroutput> option destroys the existing object, and creates a new one based on the content of the deployment. The <computeroutput>keep</computeroutput> option maintains the existing object deployment, or creates a new one if it does not exist. + </para> +<programlisting><![CDATA[ +<!ELEMENT instance (instance-id,portlet-ref,display-name*,preferences?, +security-constraint?, (display-name* | (resource-bundle, supported-locale+)))>]]> +</programlisting> + <para> + The <computeroutput>&lt;instance&gt;</computeroutput> element is used in the <filename>WEB-INF/portlet-instances.xml</filename> file, which creates instances of portlets. The portlet will only be created and configured if the portlet is present, and if an instance with the same name does not already exist. + </para> + <para> + The following is an example of the <computeroutput>&lt;instance&gt;</computeroutput> element, which also contains the <computeroutput>&lt;security-constraint&gt;</computeroutput> element. Descriptions of each element follow afterwards: + </para> +<programlisting role="XML"><![CDATA[ +<instance> + <instance-id>MyPortletInstance</instance-id> + <portlet-ref>MyPortlet</portlet-ref> + <preferences> + <preference> + <name>abc</name> + <value>def</value> + </preference> + </preferences> + <security-constraint> + <policy-permission> + <role-name>User</role-name> + <action-name>view</action-name> + </policy-permission> + </security-constraint> +</instance>]]> +</programlisting> +<programlisting><![CDATA[ +<!ELEMENT instance-id (#PCDATA)>]]> +</programlisting> + <para> + The instance identifier. The <computeroutput>&lt;instance-id&gt;</computeroutput> value can be named anything, but it must match the <computeroutput>&lt;instance-ref&gt;</computeroutput>value given in the <filename>*-object.xml</filename> file. + </para> +<programlisting><![CDATA[ +<!ELEMENT portlet-ref (#PCDATA)>]]> +</programlisting> + <para> + The <computeroutput>&lt;portlet-ref&gt;</computeroutput> element defines the portlet that an instance represents. The <computeroutput>&lt;portlet-ref&gt;</computeroutput> value must match the <computeroutput>&lt;portlet-name&gt;</computeroutput> given in the <filename>WEB-INF/portlet.xml</filename> file. + </para> +<programlisting><![CDATA[ +<!ELEMENT preferences (preference+)>]]> +</programlisting> + <para> + The <computeroutput>&lt;preferences&gt;</computeroutput> element configures an instance with a set of preferences. + </para> +<programlisting><![CDATA[ +<!ELEMENT preference (name,value)>]]> +</programlisting> + <para> + The <computeroutput>&lt;preference&gt;</computeroutput> element configures one preference, which is part of a set of preferences. Use the <computeroutput>&lt;preferences&gt;</computeroutput> element to define a set of preferences. + </para> +<programlisting><![CDATA[ +<!ELEMENT name (#PCDATA)>]]> +</programlisting> + <para> + A name. + </para> +<programlisting><![CDATA[ +<!ELEMENT value (#PCDATA)>]]> +</programlisting> + <para> + A string value. + </para> + <programlisting><![CDATA[ +<!ELEMENT security-constraint (policy-permission*)>]]> +</programlisting> + <para> + The <computeroutput>&lt;security-constraint&gt;</computeroutput> element is a container for <computeroutput>&lt;policy-permission&gt;</computeroutput> elements. The following is an example of the <computeroutput>&lt;security-constraint&gt;</computeroutput> and <computeroutput>&lt;policy-permission&gt;</computeroutput> elements: + </para> +<programlisting role="XML"><![CDATA[ +<security-constraint> + <policy-permission> + <role-name>User</role-name> + <action-name>view</action-name> + </policy-permission> +</security-constraint> + +<security-constraint> + <policy-permission> + <unchecked/> + <action-name>view</action-name> + </policy-permission> +</security-constraint>]]> +</programlisting> +<programlisting><![CDATA[ +<!ELEMENT policy-permission (action-name*,unchecked?,role-name*)>]]> +</programlisting> + <para> + The <computeroutput>&lt;policy-permission&gt;</computeroutput> element secures a specific portlet instance based on a user's role. + </para> +<programlisting><![CDATA[ +<!ELEMENT action-name (#PCDATA)>]]> +</programlisting> + <para> + The <computeroutput>&lt;action-name&gt;</computeroutput> element defines the access rights given to the role defined. Accepted values are: + </para> + <para> + <itemizedlist> + <listitem> + <para> + <computeroutput>view</computeroutput>: users can view the page. + </para> + </listitem> + <listitem> + <para> + <computeroutput>viewrecursive</computeroutput>: users can view the page and child pages. + </para> + </listitem> + <listitem> + <para> + <computeroutput>personalize</computeroutput>: users are able personalize the page's theme. + </para> + </listitem> + <listitem> + <para> + <computeroutput>personalizerecursive</computeroutput>: users are able personalize the page and child pages themes. + </para> + </listitem> + </itemizedlist> + </para> +<programlisting><![CDATA[ +<!ELEMENT unchecked EMPTY>]]> +</programlisting> + <para> + If present, the <computeroutput>&lt;unchecked&gt;</computeroutput> element defines anyone can view the instance. + </para> +<programlisting><![CDATA[ +<!ELEMENT role-name (#PCDATA)>]]> +</programlisting> + <para> + The <computeroutput>&lt;role-name&gt;</computeroutput> element defines a role that the security constraint will apply to. The following example only allows users that are part of the <computeroutput>EXAMPLEROLE</computeroutput> role to access the instance: + </para> +<programlisting role="XML"><![CDATA[ +<role-name>EXAMPLEROLE</role-name>]]> +</programlisting> + </section> + <section> + <title>The JBoss Portal Object DTD</title> + <para> + The following items refer to elements found in the JBoss Portal Object DTD, <filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/jboss-portal.sar/dtd/portal-object_<replaceable>version_number</replaceable>.dtd</filename>: + </para> +<programlisting><![CDATA[ +<!ELEMENT deployments (deployment*)>]]> +</programlisting> + <para> + The <computeroutput>&lt;deployments&gt;</computeroutput> element is a container for <computeroutput>&lt;deployment&gt;</computeroutput> elements. + </para> +<programlisting><![CDATA[ +<!ELEMENT deployment (parent-ref?,if-exists?,(context|portal|page|window))>]]> +</programlisting> + <para> + The <computeroutput>&lt;deployment&gt;</computeroutput> element is a generic container for portal object elements. The <computeroutput>&lt;parent-ref&gt;</computeroutput> child element gives the name of the parent object that the current object will use as parent. The optional <computeroutput>&lt;if-exists&gt;</computeroutput> element defines the action to take if an instance with the same name already exists. The default behavior of the <computeroutput>&lt;if-exists&gt;</computeroutput> element is to keep the existing object, and not to create a new object. + </para> + <para> + The following is an example of the <computeroutput>&lt;deployment&gt;</computeroutput> and <computeroutput>&lt;parent-ref&gt;</computeroutput> elements: + </para> +<programlisting role="XML"><![CDATA[ +<deployment> + <parent-ref>default</parent-ref> + <page> + ... + </page> +</deployment>]]> +</programlisting> + <para> + All portal objects have a common configuration which can include: + </para> + <para> + <itemizedlist> + <listitem> + <para> + a listener: specifies the ID of a listener in the listener registry. A listener object is able to listen to portal events, which apply to the portal node hierarchy. + </para> + </listitem> + <listitem> + <para> + properties: a set of generic properties owned by the portal object. Certain properties drive the behavior of the portal object. + </para> + </listitem> + <listitem> + <para> + security-constraint: defines the security configuration for the portal object. + </para> + </listitem> + </itemizedlist> + </para> +<programlisting><![CDATA[ +<!ELEMENT parent-ref (#PCDATA)>]]> +</programlisting> + <para> + The <computeroutput>&lt;parent-ref&gt;</computeroutput> element contains a reference to the parent object. The naming convention for naming objects is to concatenate the names of the path to the object, and separate the names using a period. If the path is empty, the empty string must be used. The <computeroutput>&lt;parent-ref&gt;</computeroutput> element tells the portal where the portlet appears. The syntax for the <computeroutput>&lt;parent-ref&gt;</computeroutput> element is <computeroutput><replaceable>portal-instance</replaceable>.<replaceable>portal-page</replaceable></computeroutput>. + </para> + <para> + The following is an example of the root having an empty path: + </para> +<programlisting role="XML"> +&lt;parent-ref /&gt; +</programlisting> + <para> + The following specifies that the portlet appears in the portal instance named <computeroutput>default</computeroutput>: + </para> +<programlisting role="XML"> +&lt;parent-ref&gt;default&lt;/parent-ref&gt; +</programlisting> + <para> + The following specifies that the portlet appear in the portal instance named <computeroutput>default</computeroutput>, and on the page named <computeroutput>default</computeroutput>: + </para> +<programlisting role="XML"> +&lt;parent-ref&gt;default.default&lt;/parent-ref&gt; +</programlisting> +<programlisting><![CDATA[ +<!ELEMENT if-exists (#PCDATA)>]]> +</programlisting> + <para> + The <computeroutput>&lt;if-exists&gt;</computeroutput> element defines the action to take if an instance with the same name already exists. Accepted values are <computeroutput>overwrite</computeroutput> and <computeroutput>keep</computeroutput>. The <computeroutput>overwrite</computeroutput> option destroys the existing object, and creates a new one based on the content of the deployment. The <computeroutput>keep</computeroutput> option matains the existing object deployment, or creates a new one if it does not exist. + </para> +<programlisting><![CDATA[ +<!ELEMENT context (context-name,properties?,listener?,security-constraint?,portal*, +(display-name* | (resource-bundle, supported-locale+)))>]]> +</programlisting> + <para> + The context type of the portal object. A context type represent a node in a tree, which does not have a visual representation, and only exists under the root. A context can only have children that use the <emphasis>portal</emphasis> type. + </para> +<programlisting><![CDATA[ +<!ELEMENT context-name (#PCDATA)>]]> +</programlisting> + <para> + The context name. + </para> +<programlisting><![CDATA[ +<!ELEMENT portal (portal-name,supported-modes,supported-window-states?,properties?,listener?, +security-constraint?,page*, (display-name* | (resource-bundle, supported-locale+)))>]]> +</programlisting> + <para> + A portal object that uses the <emphasis>portal</emphasis> type. A portal type represents a virtual portal, and can only have children that use the <emphasis>page</emphasis> type. In addition to the common portal object elements, it also allows you to declare modes and window states that are supported. + </para> +<programlisting><![CDATA[ +<!ELEMENT portal-name (#PCDATA)>]]> +</programlisting> + <para> + The portal name. + </para> +<programlisting><![CDATA[ +<!ELEMENT supported-modes (mode*)>]]> +</programlisting> + <para> + The <computeroutput>&lt;supported-modes&gt;</computeroutput> elements defines the supported modes of the portal. Accepted values are <computeroutput>view</computeroutput>, <computeroutput>edit</computeroutput>, and <computeroutput>help</computeroutput>. + </para> + <para> + The following is an example of the <computeroutput>&lt;supported-mode&gt;</computeroutput> and <computeroutput>&lt;mode&gt;</computeroutput> elements: + </para> +<programlisting role="XML"><![CDATA[ +<supported-mode> + <mode>view</mode> + <mode>edit</mode> + <mode>help</mode> +</supported-mode>]]> +</programlisting> +<programlisting><![CDATA[ +<!ELEMENT mode (#PCDATA)>]]> +</programlisting> + <para> + The portlet mode value. If there are no declarations of modes or window states, the default values are <computeroutput>view</computeroutput>, <computeroutput>edit</computeroutput>, <computeroutput>help</computeroutput>, and <computeroutput>normal</computeroutput>, <computeroutput>minimized</computeroutput>, <computeroutput>maximized</computeroutput>, respectively. + </para> +<programlisting><![CDATA[ +<!ELEMENT supported-window-states (window-state*)>]]> +</programlisting> + <para> + Use the <computeroutput>&lt;supported-window-states&gt;</computeroutput> element to define the supported window states of the portal. The following is an example of the <computeroutput>&lt;supported-window-states&gt;</computeroutput> and <computeroutput>&lt;window-state&gt;</computeroutput> elements: + </para> +<programlisting role="XML"><![CDATA[ +<supported-window-states> + <window-state>normal</window-state> + <window-state>minimized</window-state> + <window-state>maximized</window-state> +</supported-window-states>]]> +</programlisting> +<programlisting><![CDATA[ +<!ELEMENT window-state (#PCDATA)>]]> +</programlisting> + <para> + Use the <computeroutput>&lt;window-state&gt;</computeroutput> element to define a window states. Accepted values are <computeroutput>normal</computeroutput>, <computeroutput>minimized</computeroutput>, and <computeroutput>maximized</computeroutput>. + </para> +<programlisting><![CDATA[ +<!ELEMENT page (page-name,properties?,listener?,security-constraint?,(page | window)*, +(display-name* | (resource-bundle, supported-locale+)))>]]> +</programlisting> + <para> + A portal object that uses the <emphasis>page</emphasis> type. A page type represents a page, and can only have children that use the <emphasis>page</emphasis> and <emphasis>window</emphasis> types. The children windows are the windows of the page, and the children pages are the subpages of the page. + </para> +<programlisting><![CDATA[ +<!ELEMENT page-name (#PCDATA)>]]> +</programlisting> + <para> + The page name. + </para> +<programlisting><![CDATA[ +<!ELEMENT window (window-name,(instance-ref|content),region,height,initial-window-state?, +initial-mode?,properties?,listener?, (display-name* | (resource-bundle, supported-locale+)))>]]> +</programlisting> + <para> + A portal object that uses the <emphasis>window</emphasis> type. A window type represents a window. Besides the common properties, a window has content, and belongs to a region on the page. + </para> + <para> + The <computeroutput>&lt;instance-ref&gt;</computeroutput> and <computeroutput>&lt;content&gt;</computeroutput> elements, configured in the <filename>WEB-INF/*-object.xml</filename> files, define the content of a window. The <computeroutput>&lt;content&gt;</computeroutput> element is generic, and describes any kind of content. The <computeroutput>&lt;instance-ref&gt;</computeroutput> element is a shortcut to define the content-type of the portlet, which points to a portlet instance. The value of <computeroutput>&lt;instance-ref&gt;</computeroutput> must match the value of one of the <computeroutput>&lt;instance-id&gt;</computeroutput> elements in the <filename>WEB-INF/portlet-instances.xml</filename> file. + </para> +<programlisting><![CDATA[ +<!ELEMENT window-name (#PCDATA)>]]> +</programlisting> + <para> + The window name value. + </para> +<programlisting><![CDATA[ +<!ELEMENT instance-ref (#PCDATA)>]]> +</programlisting> + <para> + Define the content of the window as a reference to a portlet instance. This value is the ID of a portlet instance, and must much the value of one of the <computeroutput>&lt;instance-id&gt;</computeroutput> elements in the <filename>WEB-INF/portlet-instances.xml</filename> file. The following is an example of the <computeroutput>&lt;instance-ref&gt;</computeroutput> element: + </para> +<programlisting role="XML"> +&lt;instance-ref&gt;MyPortletInstance&lt;/instance-ref&gt; +</programlisting> +<programlisting><![CDATA[ +<!ELEMENT region (#PCDATA)>]]> +</programlisting> + <para> + The region the window belongs to. The <computeroutput>&lt;region&gt;</computeroutput> element specifies where the window appears on the page. + </para> +<programlisting><![CDATA[ +<!ELEMENT height (#PCDATA)>]]> +</programlisting> + <para> + The height of the window in a particular region. + </para> +<programlisting><![CDATA[ +<!ELEMENT listener (#PCDATA)>]]> +</programlisting> + <para> + Define a listener for a portal object. This value is the ID of the listener. + </para> +<programlisting><![CDATA[ +<!ELEMENT content (content-type,content-uri)>]]> +</programlisting> + <para> + Define the content of a window in a generic manner. The content is defined by the type of content, and a URI, which acts as an identifier for the content. The following is an example of the <computeroutput>&lt;content&gt;</computeroutput> element, which is configured in the <filename>WEB-INF/*-object.xml</filename> files: + </para> +<programlisting role="XML"><![CDATA[ +<content> + <content-type>portlet</content-type> + <content-uri>MyPortletInstance</content-uri> +</content> + +<content> + <content-type>cms</content-type> + <content-uri>/default/index.html</content-uri> +</content>]]> +</programlisting> +<programlisting><![CDATA[ +<!ELEMENT content-type (#PCDATA)>]]> +</programlisting> + <para> + The content type of the window. The <computeroutput>&lt;content-type&gt;</computeroutput> element specifies the content to display, for example, a <computeroutput>portlet</computeroutput>. + </para> +<programlisting><![CDATA[ +<!ELEMENT content-uri (#PCDATA)>]]> +</programlisting> + <para> + The content URI of the window. The <computeroutput>&lt;content-uri&gt;</computeroutput> element specifies which content to display, for example, a portlet instance. To display a file from the CMS, use the <computeroutput>&lt;content-uri&gt;</computeroutput> element to define the full path to that file in the CMS. + </para> +<programlisting><![CDATA[ +<!ELEMENT properties (property*)>]]> +</programlisting> + <para> + A set of generic properties for the portal object. The <computeroutput>&lt;properties&gt;</computeroutput> elements contain definitions specific to a portal object. + </para> +<programlisting><![CDATA[ +<!ELEMENT property (name,value)>]]> +</programlisting> + <para> + A generic string property. The following table lists accepted values. This table is not exhaustive: + <table> + <title>Properties</title> + <tgroup cols="2" align="left" colsep="1" rowsep="1"> + <colspec colname="name"/> + <colspec colname="description"/> + <thead> + <row> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><computeroutput>layout.id</computeroutput></entry> + <entry>Defines the layout to use for the portal object and sub-objects if they do not override the value.</entry> + </row> + <row> + <entry><computeroutput>theme.id</computeroutput></entry> + <entry>Defines the theme used for the portal object and sub-objects if they do not override the value.</entry> + </row> + <row id="xml.default.objectname.property"> + <entry><computeroutput>portal.defaultObjectName</computeroutput></entry> + <entry>Defines the default child object. If applied to a <literal>context</literal>, it defines the default portal. If applied to a <literal>portal</literal>, it defines the default portal page.</entry> + </row> + </tbody> + </tgroup> + </table> + </para> +<programlisting><![CDATA[ +<!ELEMENT name (#PCDATA)>]]> +</programlisting> + <para> + A name value. + </para> +<programlisting><![CDATA[ +<!ELEMENT value (#PCDATA)>]]> +</programlisting> + <para> + A value. + </para> +<programlisting><![CDATA[ +<!ELEMENT security-constraint (policy-permission*)>]]> +</programlisting> + <para> + The <computeroutput>&lt;security-constraint&gt;</computeroutput> element is a container for <computeroutput>&lt;policy-permission&gt;</computeroutput> elements. The following is an example of the <computeroutput>&lt;security-constraint&gt;</computeroutput> and <computeroutput>&lt;policy-permission&gt;</computeroutput> elements: + </para> +<programlisting role="XML"><![CDATA[ +<security-constraint> + <policy-permission> + <role-name>User</role-name> + <action-name>view</action-name> + </policy-permission> +</security-constraint> + +<security-constraint> + <policy-permission> + <unchecked/> + <action-name>view</action-name> + </policy-permission> +</security-constraint>]]> +</programlisting> +<programlisting><![CDATA[ +<!ELEMENT policy-permission (action-name*,unchecked?,role-name*)>]]> +</programlisting> + <para> + The <computeroutput>&lt;policy-permission&gt;</computeroutput> element is secures a specific portlet instance based on a user's role. + </para> +<programlisting><![CDATA[ +<!ELEMENT action-name (#PCDATA)>]]> +</programlisting> + <para> + The <computeroutput>&lt;action-name&gt;</computeroutput> element defines the access rights given to the role defined. Accepted values are: + </para> + <para> + <itemizedlist> + <listitem> + <para> + <computeroutput>view</computeroutput>: users can view the page. + </para> + </listitem> + <listitem> + <para> + <computeroutput>viewrecursive</computeroutput>: users can view the page and child pages. + </para> + </listitem> + <listitem> + <para> + <computeroutput>personalize</computeroutput>: users are able personalize the page's theme. + </para> + </listitem> + <listitem> + <para> + <computeroutput>personalizerecursive</computeroutput>: users are able personalize the page and child pages themes. + </para> + </listitem> + </itemizedlist> + </para> +<programlisting><![CDATA[ +<!ELEMENT unchecked EMPTY>]]> +</programlisting> + <para> + If present, the <computeroutput>&lt;unchecked&gt;</computeroutput> element defines that anyone can view the instance. + </para> +<programlisting><![CDATA[ +<!ELEMENT role-name (#PCDATA)>]]> +</programlisting> + <para> + The <computeroutput>&lt;role-name&gt;</computeroutput> element defines a role that the security constraint applies to. The following example only allows users that are part of the <computeroutput>EXAMPLEROLE</computeroutput> role to access the instance: + </para> +<programlisting><![CDATA[ +<role-name>EXAMPLEROLE</role-name>]]> +</programlisting> + </section> + <section> + <title>The JBoss Portal App DTD</title> + <para> + The following items refer to elements found in the JBoss Portal App DTD, <filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/jboss-portal.sar/dtd/jboss-app_<replaceable>version_number</replaceable>.dtd</filename>: + </para> +<programlisting><![CDATA[ +<Element <![CDATA[<!ELEMENT jboss-app (app-name?)>]]> +</programlisting> +<programlisting><![CDATA[ +<!DOCTYPE jboss-app PUBLIC + "-//JBoss Portal//DTD JBoss Web Application 2.6//EN" + "http://www.jboss.org/portal/dtd/jboss-app_2_6.dtd">]]> +</programlisting> +<programlisting><![CDATA[ +<!ELEMENT app-name (#PCDATA)>]]> +</programlisting> + <para> + When a web application is deployed, the context path under which it is deployed + is taken as the application name. The application name value in the <computeroutput>&lt;app-name&gt;</computeroutput> element overrides it. When a component references a portlet, it needs to reference the application too, and if the portlet application WAR file is renamed, + the reference is no longer valid; therefore, the <computeroutput>&lt;app-name&gt;</computeroutput> element is used to have an application name that does not depend upon the context path, under which the application is deployed. + </para> + </section> + </section> + <section id="descriptors_portlet"> + <title>Portlet Descriptors</title> + <para> + The following sections describe the descriptors that define portal objects, such as portals, pages, portlet instances, windows, and portlets. Refer to <xref linkend="tutorials_tutorials"/> and <xref linkend="desc_examples"/> for examples on using these descriptors within a portlet application. + </para> + <section id="desc_objectxml"> + <title><filename>*-object.xml</filename> Descriptors</title> + <para> + The <filename>*-object.xml</filename> descriptors define portal instances, pages, windows, and the window layout. As well, themes and layouts for specific portal instances, pages, and windows, can be defined. The following example defines a portlet window being added to the <computeroutput>default</computeroutput> page, in the <computeroutput>default</computeroutput> portal. For advanced functionality using these descriptors, refer to <xref linkend="desc_examples"/>: + </para> + <programlisting role="XML"><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE deployments PUBLIC + "-//JBoss Portal//DTD Portal Object 2.6//EN" + "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd"> +<deployments> + <deployment> + <parent-ref>default.default</parent-ref> + <if-exists>overwrite</if-exists> + <window> + <window-name>HelloWorldJSPPortletWindow</window-name> + <instance-ref>HelloWorldJSPPortletInstance</instance-ref> + <region>center</region> + <height>1</height> + </window> + </deployment> +</deployments>]]></programlisting> + <itemizedlist> + <listitem> + <para> + <programlisting><![CDATA[<deployments>...</deployments>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;deployments&gt;</computeroutput> element encapsulates the entire document, and is a container for <computeroutput>&lt;deployment&gt;</computeroutput> elements. Multiple deployments can be specified within the <computeroutput>&lt;deployments&gt;</computeroutput> element. + </para> + </listitem> + <listitem> + <para> + <programlisting><![CDATA[<deployment>...</deployment>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;deployment&gt;</computeroutput> element specifies object deployments, such as portals, pages, windows, and so on. + </para> + </listitem> + <listitem> + <para> + <programlisting><![CDATA[<if-exists>...</if-exists>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;if-exists&gt;</computeroutput> element defines the action to take if an instance with the same name already exists. Accepted values are <computeroutput>overwrite</computeroutput> and <computeroutput>keep</computeroutput>. The <computeroutput>overwrite</computeroutput> option destroys the existing object, and creates a new one based on the content of the deployment. The <computeroutput>keep</computeroutput> option maintains the existing object deployment, or creates a new one if it does not exist. + </para> + </listitem> + <listitem> + <para> + <programlisting><![CDATA[<parent-ref>...</parent-ref>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;parent-ref&gt;</computeroutput> element contains a reference to the parent object. The naming convention for naming objects is to concatenate the names of the path to the object, and separate the names using a period. If the path is empty, the empty string must be used. The <computeroutput>&lt;parent-ref&gt;</computeroutput> element tells the portal where the portlet appears. The syntax for the <computeroutput>&lt;parent-ref&gt;</computeroutput> element is <computeroutput><replaceable>portal-instance</replaceable>.<replaceable>portal-page</replaceable></computeroutput>. + </para> + <para> + In the example above, a window is defined, and assigned to <computeroutput>default.default</computeroutput>. This means the window appears on the <computeroutput>default</computeroutput> page, in the <computeroutput>default</computeroutput> portal. + </para> + </listitem> + <listitem> + <para> + <programlisting><![CDATA[<window>...</window>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;window&gt;</computeroutput> element defines a portlet window. The <computeroutput>&lt;window&gt;</computeroutput> element requires an <computeroutput>&lt;instance-ref&gt;</computeroutput> element, which assigns a portal instance to a window. + </para> + </listitem> + <listitem> + <para> + <programlisting><![CDATA[<window-name>...</window-name>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;window-name&gt;</computeroutput> element defines the <emphasis role="bold">unique name</emphasis> given to a portlet window. This can be named anything. + </para> + </listitem> + <listitem> + <para> + <programlisting><![CDATA[<instance-ref>...</instance-ref>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;instance-ref&gt;</computeroutput> elements define the portlet instances that windows represent. This value is the ID of a portlet instance, and must match the value of one of the <computeroutput>&lt;instance-id&gt;</computeroutput> elements in the <filename>WEB-INF/portlet-instances.xml</filename> file. + </para> + </listitem> + <listitem> + <para> +<programlisting><![CDATA[ +<region>...</region> +<height>...</height>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;region&gt;</computeroutput> and <computeroutput>&lt;height&gt;</computeroutput> elements define where the window appears within the page layout. The <computeroutput>&lt;region&gt;</computeroutput> element specifies where the window appears on the page. The <computeroutput>&lt;region&gt;</computeroutput> element often depends on other regions defined in the portal layout. The <computeroutput>&lt;height&gt;</computeroutput> element can be assigned a value between one and <replaceable>X</replaceable>. + </para> + </listitem> + </itemizedlist> + <para>The previous <filename>*-object.xml</filename> example makes reference to items found in other descriptor files. The following diagram illustrates the relationship between the <filename>portlet.xml</filename>, <filename>portlet-instances.xml</filename>, and <filename>*-object.xml</filename> descriptors: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/tutorials/first_portlet/desc_relationship.png" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + <para> + <note> + <title>Are <filename>*-object.xml</filename> descriptors required?</title> + <para> + Technically, they are not. The portal object hierarchy, such as creating portals, pages, instances, and organizing them on the page, can be defined using the management portlet, which is accessible to JBoss Portal administrators. + </para> + </note> + </para> + </section> + <section id="desc_instancesxml"> + <title>The <filename>portlet-instances.xml</filename> Descriptor</title> + <para> + The <filename>portlet-instances.xml</filename> descriptor is JBoss Portal specific, and allows developers to instantiate one-or-many instances of one-or-many portlets. The benefit of this allows one portlet to be instantiated several times, with different preference parameters. The following example instantiates two separate instances of the <computeroutput>NewsPortlet</computeroutput>, both using different parameters. One instance draws feeds from Red Hat announcements, and the other from McDonalds announcements: + </para> + <para> +<programlisting><![CDATA[ +<?xml version="1.0" standalone="yes"?> +<!DOCTYPE deployments PUBLIC + "-//JBoss Portal//DTD Portlet Instances 2.6//EN" + "http://www.jboss.org/portal/dtd/portlet-instances_2_6.dtd"> +<deployments> + <deployment> + <instance> + <instance-id>NewsPortletInstance1</instance-id> + <portlet-ref>NewsPortlet</portlet-ref> + <preferences> + <preference> + <name>expires</name> + <value>180</value> + </preference> + <preference> + <name>RssXml</name> + <value>http://finance.yahoo.com/rss/headline?s=rhat</value> + </preference> + </preferences> + <security-constraint> + <policy-permission> + <action-name>view</action-name> + <unchecked/> + </policy-permission> + </security-constraint> + </instance> + </deployment> + <deployment> + <instance> + <instance-id>NewsPortletInstance2</instance-id> + <portlet-ref>NewsPortlet</portlet-ref> + <preferences> + <preference> + <name>expires</name> + <value>180</value> + </preference> + <preference> + <name>RssXml</name> + <value>http://finance.yahoo.com/rss/headline?s=mcd</value> + </preference> + </preferences> + <security-constraint> + <policy-permission> + <action-name>view</action-name> + <unchecked/> + </policy-permission> + </security-constraint> + </instance> + </deployment> +</deployments> +]]></programlisting> + </para> + <para> + <itemizedlist> + <listitem> + <para> + <programlisting><![CDATA[<deployments>...</deployments>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;deployments&gt;</computeroutput> element encapsulates the entire document, and is a container for <computeroutput>&lt;deployment&gt;</computeroutput> elements. Multiple deployments can be specified within the <computeroutput>&lt;deployments&gt;</computeroutput> element. + </para> + </listitem> + <listitem> + <para> +<programlisting><![CDATA[ +<deployment> + <instance>...</instance> +</deployment>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;deployment&gt;</computeroutput> element, and the embedded <computeroutput>&lt;instance&gt;</computeroutput> element, specify a portlet instance. The <computeroutput>&lt;deployment&gt;</computeroutput> element specifies object deployments, such as portals, pages, windows, and so on. The <computeroutput>&lt;instance&gt;</computeroutput> element creates instances of portlets. The portlet will only be created and configured if the portlet is present, and if an instance with the same name does not already exist. + </para> + </listitem> + <listitem> + <para> + <programlisting><![CDATA[<instance-id>...</instance-id>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;instance-id&gt;</computeroutput> elements defines a <emphasis role="bold">unique name</emphasis> given to an instance of a portlet. The <computeroutput>&lt;instance-id&gt;</computeroutput> value can be named anything, but it must match the value of one of the <computeroutput>&lt;instance-ref&gt;</computeroutput> elements in the <filename>WEB-INF/*-object.xml</filename> file. + </para> + </listitem> + <listitem> + <para> + <programlisting><![CDATA[<portlet-ref>...</portlet-ref>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;portlet-ref&gt;</computeroutput> element defines the portlet that an instance represents. The <computeroutput>&lt;portlet-ref&gt;</computeroutput> value must match the <computeroutput>&lt;portlet-name&gt;</computeroutput> given in the <filename>WEB-INF/portlet.xml</filename> file. + </para> + </listitem> + <listitem> + <para> +<programlisting><![CDATA[ +<preferences> + <preference>...</preference> +</preferences>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;preference&gt;</computeroutput> element configures a preference as a key-value pair. This value can be composed of a single string value, for example, the preference <emphasis>fruit</emphasis> can have the <emphasis>apple</emphasis> value. As well, this value can be composed of multiple strings, for example, the preference <emphasis>fruits</emphasis> can have values of <emphasis>apple</emphasis>, <emphasis>orange</emphasis>, and <emphasis>kiwi</emphasis>: + </para> + <para> +<programlisting><![CDATA[ +<preferences> + <preference> + <name>fruits</name> + <value>apple</value> + <value>orange</value> + <value>kiwi</value> + </preference> +</preferences> +]]></programlisting> + </para> + <para> + The <computeroutput>&lt;preference&gt;</computeroutput> element configures one preference, which is part of a set of preferences. Use the <computeroutput>&lt;preferences&gt;</computeroutput> element to define a set of preferences. + </para> + </listitem> + <listitem> + <para> +<programlisting><![CDATA[<security-constraint> + <policy-permission> + <action-name>viewrecursive</action-name> + <unchecked/> + </policy-permission> +</security-constraint>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;security-constraint&gt;</computeroutput> element is a container for <computeroutput>&lt;policy-permission&gt;</computeroutput> elements. This example demonstrates the <computeroutput>&lt;security-constraint&gt;</computeroutput> and <computeroutput>&lt;policy-permission&gt;</computeroutput> elements. + </para> + <para> + The <computeroutput>&lt;action-name&gt;</computeroutput> element defines the access rights given to the role defined. Accepted values are: + </para> + <para> + <itemizedlist> + <listitem override="bullet"> + <para> + <computeroutput>view</computeroutput>: users can view the page. + </para> + </listitem> + <listitem override="bullet"> + <para> + <computeroutput>viewrecursive</computeroutput>: users can view the page and child pages. + </para> + </listitem> + <listitem override="bullet"> + <para> + <computeroutput>personalize</computeroutput>: users are able personalize the page's theme. + </para> + </listitem> + <listitem override="bullet"> + <para> + <computeroutput>personalizerecursive</computeroutput>: users are able personalize the page and child pages themes. + </para> + </listitem> + </itemizedlist> + </para> + <para> + You must define a role that the security constraint will apply to: + </para> + <para> + <itemizedlist> + <listitem override="bullet"> + <para> + <computeroutput>unchecked</computeroutput>: anyone can view the page. + </para> + </listitem> + <listitem override="bullet"> + <para> + <computeroutput>&lt;role-name&gt;EXAMPLEROLE&lt;/role-name&gt;</computeroutput>: only allow users that are part of the <computeroutput>EXAMPLEROLE</computeroutput> role to access the instance. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> +</itemizedlist> +</para> + <para> + The previous <filename>portlet-instances.xml</filename> example makes reference to items found in other descriptor files. The following diagram illustrates the relationship between the <filename>portlet.xml</filename>, <filename>portlet-instances.xml</filename>, and <filename>*-object.xml</filename> descriptors: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/tutorials/first_portlet/desc_relationship.png" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + <note> + <title>Is the <filename>portlet-instances.xml</filename> descriptor required?</title> + <para> + Technically, it is not. The portal object hierarchy, such as creating portals, pages, instances, and organizing them on the page, can be defined using the management portlet, which is accessible to JBoss Portal administrators. + </para> + </note> + </section> + <section> + <title>The <filename>jboss-portlet.xml</filename> Descriptor</title> + <para> + The <filename>jboss-portlet.xml</filename> descriptor allows you to use JBoss-specific functionality within your portlet application. This descriptor is covered by the <ulink url="http://www.jcp.org/en/jsr/detail?id=168">JSR-168 Portlet Specification</ulink>, and is normally packaged inside your portlet WAR file, alongside the other descriptors in these sections. + </para> + <section> + <title>Injecting Header Content</title> + <para> + The following example injects a specific style sheet, <computeroutput>/images/management/management.css</computeroutput>, allowing the portlet to leverage a specific style: + </para> + <para> +<programlisting><![CDATA[ +<?xml version="1.0" standalone="yes"?> +<!DOCTYPE portlet-app PUBLIC + "-//JBoss Portal//DTD JBoss Portlet 2.6//EN" + "http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd"> +<portlet-app> + <portlet> + <portlet-name>ManagementPortlet</portlet-name> + <header-content> + <link rel="stylesheet" type="text/css" href="/images/management/management.css" + media="screen"/> + </header-content> + </portlet> +</portlet-app>]]> +</programlisting> + </para> + <para> + Use the <computeroutput>&lt;header-content&gt;</computeroutput> and <computeroutput>&lt;link&gt;</computeroutput> elements to specify a style sheet. + </para> + </section> + <section> + <title>Injecting Services in the portlet Context</title> + <para> + The following example injects the <computeroutput>UserModule</computeroutput> service as an attribute to the portlet context: + </para> + <para> +<programlisting><![CDATA[ +<?xml version="1.0" standalone="yes"?> +<!DOCTYPE portlet-app PUBLIC + "-//JBoss Portal//DTD JBoss Portlet 2.6//EN" + "http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd"> +<portlet-app> + <service> + <service-name>UserModule</service-name> + <service-class>org.jboss.portal.identity.UserModule</service-class> + <service-ref>:service=Module,type=User</service-ref> + </service> +</portlet-app>]]> +</programlisting> + </para> + <para> + This allows the portlet to leverage the service, for example: + </para> + <para> +<programlisting><![CDATA[ +UserModule userModule = (UserModule) getPortletContext().getAttribute("UserModule"); +String userId = request.getParameters().getParameter("userid"); +User user = userModule.findUserById(userId);]]> +</programlisting> + </para> + </section> + <section> + <title>Defining extra portlet Information</title> + <para> + As of JBoss Portal 2.6.3, icons can be defined for a portlet by using the <computeroutput>&lt;icon&gt;</computeroutput>, <computeroutput>&lt;small-icon&gt;</computeroutput>, and <computeroutput>&lt;large-icon&gt;</computeroutput> elements: + </para> + <para> +<programlisting><![CDATA[ +<?xml version="1.0" standalone="yes"?> +<!DOCTYPE portlet-app PUBLIC + "-//JBoss Portal//DTD JBoss Portlet 2.6//EN" + "http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd"> +<portlet-app> + <portlet> + <portlet-name>ManagementPortlet</portlet-name> + <portlet-info> + <icon> + <small-icon>/images/smallIcon.png</small-icon> + <large-icon>/images/largeIcon.png</small-icon> + </icon> + </portlet-info> + </portlet> +</portlet-app>]]> +</programlisting> + </para> + <para> + References to icons can be absolute, for example, <emphasis>http://www.example.com/images/smallIcon.png</emphasis>;, or relative to the web application context, for example, <computeroutput>/images/smallIcon.png</computeroutput>. Icons can be used by different parts of the portlet user interface. + </para> + </section> + <section> + <title>Portlet Session Replication in a Clustered Environment</title> + + <para> + For information about portlet session replication in clustered environments, refer to <xref linkend="portlet_session_replication"/>. + </para> + <para> + <note> + <title>Is the <filename>jboss-portlet.xml</filename> descriptor required?</title> + <para> + Technically, it is not; however, it may be required to access JBoss-specific functionality that is not covered by the Portlet specification. + </para> + </note> + </para> + </section> + </section> + <section> + <title>The <filename>portlet.xml</filename> Descriptor</title> + <para> + The <filename>portlet.xml</filename> descriptor is the standard portlet descriptor covered by the <ulink url="http://www.jcp.org/en/jsr/detail?id=168">JSR-168 Portlet Specification</ulink>. Developers are strongly encouraged to read the <ulink url="http://www.jcp.org/en/jsr/detail?id=168">JSR-168 Portlet Specification</ulink> items covering the correct use of this descriptor, as it is only covered briefly in these sections. Normally the <filename>portlet.xml</filename> descriptor is packaged inside your portlet WAR file, alongside the other descriptors in these sections. The following example is a modified version of the JBoss Portal UserPortlet definition: + </para> + <para> +<programlisting><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<portlet-app + xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1... + http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" + version="1.0"> + <portlet> + <description>Portlet providing user login/logout and profile management</description> + <portlet-name>UserPortlet</portlet-name> + <display-name>User Portlet</display-name> + <portlet-class>org.jboss.portal.core.portlet.user.UserPortlet</portlet-class> + <init-param> + <description>Initialize the portlet with a default page to render</description> + <name>>default-view</name> + <value>/WEB-INF/jsf/objects.xhtml</value> + </init-param> + <supports> + <mime-type>text/html</mime-type> + <portlet-mode>VIEW</portlet-mode> + </supports> + <supported-locale>en</supported-locale> + <supported-locale>fr</supported-locale> + <supported-locale>es</supported-locale> + <resource-bundle>Resource</resource-bundle> + <portlet-info> + <title>User portlet</title> + </portlet-info> + </portlet> +</portlet-app>]]> +</programlisting> + </para> + <para> + <itemizedlist> + <listitem> + <para> + <programlisting><![CDATA[<portlet-app>...</portlet-app>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;portlet-app&gt;</computeroutput> element encapsulates the entire document. Multiple portlets can be specified using the <computeroutput>&lt;portlet-app&gt;</computeroutput> element. + </para> + </listitem> + <listitem> + <para> + <programlisting><![CDATA[<portlet>...</portlet>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;portlet&gt;</computeroutput> element defines one portlet that is deployed within this archive. + </para> + </listitem> + <listitem> + <para> + <programlisting><![CDATA[<description>...</description>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;description&gt;</computeroutput> element is a verbal description of the portlet's function. + </para> + </listitem> + <listitem> + <para> + <programlisting><![CDATA[<portlet-name>...</portlet-name>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;portlet-name&gt;</computeroutput> element defines the portlet name. It does not have to be the class name. + </para> + </listitem> + <listitem> + <para> + <programlisting><![CDATA[<portlet-class>...</portlet-class>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;portlet-class&gt;</computeroutput> element defines the Fully Qualified Name (FQN) of the portlet class. + </para> + </listitem> + <listitem> + <para> + <programlisting><![CDATA[ +<init-param> + <name>...</name> + <value>...</value> +</init-param>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;init-param&gt;</computeroutput> element specifies initialization parameters to create an initial state inside your portlet class. This is usually used in the portlet's <emphasis>init()</emphasis> method, but not necessarily. Unlike a preference, an init-parameter is data that does not change at runtime and does not go into a database. If the value is changed in the descriptor, the change takes immediate effect after re-deploying the portlet. Multiple <computeroutput>&lt;init-param&gt;</computeroutput> elements can be used. + </para> + </listitem> + <listitem> + <para> + <programlisting><![CDATA[<supports>...</supports>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;supports&gt;</computeroutput> element declares all of the markup types that a portlet supports. Use the <computeroutput>&lt;mime-type&gt;</computeroutput> element to declare supported capabilities, for example, if the only outputs are text and HTML, use <computeroutput>&lt;mime-type&gt;text/html&lt;/mime-type&gt;</computeroutput>. Use the <computeroutput>&lt;portlet-mode&gt;</computeroutput> element to define the supported portlet modes for the portlet. For example, all portlets must support the <computeroutput>view</computeroutput> portlet mode, which is defined using <computeroutput>&lt;portlet-mode&gt;view&lt;/portlet-mode&gt;</computeroutput>. + </para> + </listitem> + <listitem> + <para> + <programlisting><![CDATA[<supported-locale>...</supported-locale>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;supported-locale&gt;</computeroutput> elements advertise the supported locales for the portlet. Use multiple <computeroutput>&lt;supported-locale&gt;</computeroutput> elements to specify multiple locales. + </para> + </listitem> + <listitem> + <para> + <programlisting><![CDATA[<resource-bundle>...</resource-bundle>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;resource-bundle&gt;</computeroutput> element specifies the resource bundle that contains the localized information for the specified locales. + </para> + </listitem> + <listitem> + <para> + <programlisting><![CDATA[ +<portlet-info> + <title>...</title> +</portlet-info>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;title&gt;</computeroutput> element defines the portlet's title, which is displayed in the portlet window's title bar. + </para> + </listitem> + </itemizedlist> + </para> + <para> + <warning> + <title>The <filename>portlet.xml</filename> Example</title> + <para> + This <filename>portlet.xml</filename> example is not a replacement for what is covered in the <ulink url="http://www.jcp.org/en/jsr/detail?id=168">JSR-168 Portlet Specification</ulink>. + </para> + </warning> + </para> + </section> + </section> + <section id="portaldescriptors"> + <title>JBoss Portal Descriptors</title> + <para> + This section describes Datasource descriptors, which are required for JBoss Portal to communicate with a database, and briefly covers the <filename>jboss-portal.sar/conf/config.xml</filename> descriptor, which can be used for configuring logging, and configuring which page a user goes to when they log in. + </para> + <section id="descriptor_ds"> + <title>Datasource Descriptors (<filename>portal-*-ds.xml</filename>)</title> + <para> + JBoss Portal requires a Datasource descriptor to be deployed alongside the <filename>jboss-portal.sar</filename>, in order to communicate with a database. This section explains where to obtain template Datasource descriptors, how to compile them from source, and how to configure them for your installation. For an in-depth introduction to datasources, refer to the JBoss AS documentation online on the <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=ConfigDataSources"... Datasource Wiki page</ulink>. + </para> + <section> + <title>Datasource Descriptors included in Binary releases</title> + <para> + Several template Datasource descriptors are included in the binary and bundled distributions of JBoss Portal. They are commonly located in the <filename>jboss-portal-<replaceable>version</replaceable>/setup/</filename> directory: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/setup/package.png" valign="middle"/> + </imageobject> + </mediaobject> + </para> + <para> + The <filename>jboss-portal-<replaceable>version</replaceable>/setup/</filename> directory contains sample Datasource descriptors for the MySQL, Microsoft SQL Server, PostgreSQL, and Oracle databases, which can be customized for your own database: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/setup/dsfiles.png" valign="middle"/> + </imageobject> + </mediaobject> + </para> + </section> + <section> + <title>Building Datasource Descriptors from Source</title> + <para> + To build the Datasource descriptors from source: + </para> + <para> + <orderedlist> + <listitem> + <para> + Obtain the JBoss Portal source code: <xref linkend="install_source"/>. + </para> + </listitem> + <listitem> + <para> + Configure the <computeroutput>JBOSS_HOME</computeroutput> environment variable: <xref linkend="install_source_env"/>. + </para> + </listitem> + <listitem> + <para> + Change into the <filename>JBOSS_PORTAL_SOURCE_DIRECTORY/build/</filename> directory. To build the JBoss Portal source code on Linux, run the <command>sh build.sh deploy</command> command, or, if you are running Windows, run the <command>build.bat deploy</command> command. If this is the first build, third-party libraries are obtained from an online repository, so you must be connected to the Internet. After building, if the <filename>JBOSS_PORTAL_SOURCE_DIRECTORY/thirdparty/</filename> directory does not exist, it is created, and populated with the files required for later steps. For further details, refer to <xref linkend="building_deploying_from_source"/>. + </para> + </listitem> + <listitem> + <para> + Change into the <filename>JBOSS_PORTAL_SOURCE_DIRECTORY/core/</filename> directory, and run the <command>sh build.sh datasource</command> command, or, if you are running Windows, run the <command>build.bat datasource</command> command: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/setup/build_ds.png" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + </listitem> + </orderedlist> + </para> + <para> + Note: if the JBoss Portal source was not built as per step 3, the <command>sh build.sh datasource</command> and <command>build.bat datasource</command> commands fail with an error, such as the following: + </para> + <para> +<programlisting><![CDATA[ +BUILD FAILED +java.io.FileNotFoundException: /jboss-portal-2.6.3.GA-src/core/../thirdparty/libraries.ent +(No such file or directory)]]> +</programlisting> + </para> + <para> + The datasource build process produces the following directory and file structure, with the Datasource descriptors in the <filename>JBOSS_PORTAL_SOURCE_DIRECTORY/core/output/resources/setup</filename> directory: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/setup/build_ds_dir.png"/> + </imageobject> + </mediaobject> + </para> + <para> + The following is an example Datasource descriptor for a PostgreSQL database: + </para> + <para> +<programlisting><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<datasources> + <local-tx-datasource> + <jndi-name>PortalDS</jndi-name> + <connection-url>jdbc:postgresql:jbossportal</connection-url> + <driver-class>org.postgresql.Driver</driver-class> + <user-name>portal</user-name> + <password>portalpassword</password> + </local-tx-datasource> +</datasources>]]> +</programlisting> + </para> + <para> + Make sure the <computeroutput>user-name</computeroutput>, <computeroutput>password</computeroutput>, <computeroutput>connection-url</computeroutput>, and <computeroutput>driver-class</computeroutput>, are correct for your chosen database. + </para> + </section> + </section> + <section id="descriptor_debug"> + <title>Portlet Debugging (<filename>jboss-portal.sar/conf/config.xml</filename>)</title> + <para> + By default, JBoss Portal is configured to display all errors. This behavior can be configured by modifying the <filename>jboss-portal.sar/conf/config.xml</filename> file: + </para> + <para> +<programlisting><![CDATA[ +<!-- When a window has restrictedaccess : show or hide values are permitted --> +<entry key="core.render.window_access_denied">show</entry> +<!-- When a window is unavailable : show or hide values are permitted --> +<entry key="core.render.window_unavailable">show</entry> +<!-- When a window produces an error : show, hide or message_only values are permitted --> +<entry key="core.render.window_error">message_only</entry> +<!-- When a window produces an internal error : show, hide are permitted --> +<entry key="core.render.window_internal_error">show</entry> +<!-- When a window is not found : show or hide values are permitted --> +<entry key="core.render.window_not_found">show</entry>]]> +</programlisting> + </para> + <para> + For these parameters, accepted values are <computeroutput>show</computeroutput> and <computeroutput>hide</computeroutput>. Depending on the setting, and the actual error, either an error message is displayed, or a full stack trace within the portlet window occurs. Additionally, the <computeroutput>core.render.window_error</computeroutput> property supports the <computeroutput>message_only</computeroutput> value. The <computeroutput>message_only</computeroutput> value will only display an error message, whereas the <computeroutput>show</computeroutput> value will, if available, display the full stack trace. + </para> + </section> + <section> + <title>Log in to Dashboard</title> + <para> + By default, when a user logs in they are forwarded to the default page of the default portal. In order to + forward a user to their Dashboard, set the <computeroutput>core.login.namespace</computeroutput> value to <computeroutput>dashboard</computeroutput> in the <filename>jboss-portal.sar/conf/config.xml</filename> file: + </para> + <para> +<programlisting><![CDATA[ +<!-- Namespace to use when logging-in, use "dashboard" to directly +log-in the dashboard otherwise use "default" --> +<entry key="core.login.namespace">dashboard</entry> +]]></programlisting> + </para> + </section> + </section> + <section id="desc_examples"> + <title>Descriptor Examples</title> + <section id="desc_example_page"> + <title>Defining a new Portal Page</title> + <para> + The sample application descriptor in this section creates a new page, <computeroutput>MyPage</computeroutput>, in a portal. To illustrate this example, download the <ulink url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles... portlet. To use the HelloWorldPortalPage portlet: + </para> + <para> + <orderedlist> + <listitem> + <para> + Download the <ulink url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles... portlet. + </para> + </listitem> + <listitem> + <para> + Unzip the <filename>HelloWorldPortalPage</filename> ZIP file. + </para> + </listitem> + <listitem> + <para> + To expand the WAR file, which gives you access to the XML descriptors, change into the <filename>HelloWorldPortalPage/</filename> directory, and run the <command>ant explode</command> command. + </para> + </listitem> + <listitem> + <para> + If you did not expand the <filename>helloworldportalpage.war</filename> file, copy the <filename>helloworldportalpage.war</filename> file into the correct JBoss AS or JBoss EAP <filename>deploy/</filename> directory. If you expanded the <filename>helloworldportalpage.war</filename> file, copy the <filename>HelloWorldPortalPage/output/lib/exploded/helloworldportalpage.war/</filename> directory into the correct JBoss AS or JBoss EAP <filename>deploy/</filename> directory. For example, if you are using the <computeroutput>default</computeroutput> JBoss AS profile, copy the WAR file or the expanded directory into the <filename>$JBOSS_HOME/server/default/deploy/</filename> directory. + </para> + </listitem> + </orderedlist> + </para> + <para> + The HelloWorldPortalPage portlet is hot-deployable, so the JBoss EAP or JBoss AS server does not have to be restarted after deploying the HelloWorldPortalPage portlet. The following is an example of the <filename>HelloWorldPortalPage/WEB-INF/helloworld-object.xml</filename> descriptor: + </para> + <para> +<programlisting><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE deployments PUBLIC + "-//JBoss Portal//DTD Portal Object 2.6//EN" + "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd"> +<deployments> + <deployment> + <if-exists>overwrite</if-exists> + <parent-ref>default</parent-ref> + <properties/> + <page> + <page-name>MyPage</page-name> + <window> + <window-name>HelloWorldPortletPageWindow</window-name> + <instance-ref>HelloWorldPortletPageInstance</instance-ref> + <region>center</region> + <height>0</height> + </window> + <security-constraint> + <policy-permission> + <unchecked/> + <action-name>viewrecursive</action-name> + </policy-permission> + </security-constraint> + </page> + </deployment> +</deployments>]]> +</programlisting> + </para> + <para> + A depoloyment is composed of a <computeroutput>&lt;deployments&gt;</computeroutput> element, which is a container for <computeroutput>&lt;deployment&gt;</computeroutput> elements. In the previous example, a page is defined, the portlet is placed as a window on a page, and an instance of the portlet is created. The Mangement portlet (bundled with JBoss Portal) can modify portal instances, page position, and so on. + </para> + <para> + The following list describes elements in a <filename>*-object.xml</filename> file: + </para> + <para> + <itemizedlist> + <listitem> +<programlisting> +&lt;if-exists&gt; +</programlisting> + <para> + The <computeroutput>&lt;if-exists&gt;</computeroutput> element defines the action to take if an instance with the same name already exists. Accepted values are <computeroutput>overwrite</computeroutput> and <computeroutput>keep</computeroutput>. The <computeroutput>overwrite</computeroutput> option destroys the existing object, and creates a new one based on the content of the deployment. The <computeroutput>keep</computeroutput> option matains the existing object deployment, or creates a new one if it does not exist. + </para> + </listitem> + <listitem> +<programlisting> +&lt;parent-ref&gt; +</programlisting> + <para> + The <computeroutput>&lt;parent-ref&gt;</computeroutput> element contains a reference to the parent object. The naming convention for naming objects is to concatenate the names of the path to the object, and separate the names using a period. If the path is empty, the empty string must be used. The <computeroutput>&lt;parent-ref&gt;</computeroutput> element tells the portal where the portlet appears. The syntax for the <computeroutput>&lt;parent-ref&gt;</computeroutput> element is <computeroutput><replaceable>portal-instance</replaceable>.<replaceable>portal-page</replaceable></computeroutput>. + </para> + </listitem> + <listitem> +<programlisting> +&lt;properties&gt; +</programlisting> + <para> + A set of generic properties for the portal object. The <computeroutput>&lt;properties&gt;</computeroutput> elements contains definitions specific to a page. This is commonly used to define the specific theme and layout to use. If not defined, the default portal theme and layout are used. + </para> + </listitem> + <listitem> +<programlisting> +&lt;page&gt; +</programlisting> + <para> + The start of a page definition. Among others, the <computeroutput>&lt;page&gt;</computeroutput> element is a container for the <computeroutput>&lt;page-name&gt;</computeroutput>, <computeroutput>&lt;window&gt;</computeroutput>, and <computeroutput>&lt;security-constraint&gt;</computeroutput> elements. + </para> + </listitem> + <listitem> +<programlisting> +&lt;page-name&gt; +</programlisting> + <para> + The page name. + </para> + </listitem> + <listitem> +<programlisting> +&lt;window&gt; +</programlisting> + <para> + The <computeroutput>&lt;window&gt;</computeroutput> element defines a portlet window. The <computeroutput>&lt;window&gt;</computeroutput> element requires an <computeroutput>&lt;instance-ref&gt;</computeroutput> element, which assigns a portal instance to a window. + </para> + </listitem> + <listitem> +<programlisting> +&lt;window-name&gt; +</programlisting> + <para> + The <computeroutput>&lt;window-name&gt;</computeroutput> element defines the <emphasis role="bold">unique name</emphasis> given to a portlet window. This can be named anything. + </para> + </listitem> + <listitem> +<programlisting> +&lt;instance-ref&gt; +</programlisting> + <para> + The <computeroutput>&lt;instance-ref&gt;</computeroutput> elements define the portlet instances that windows represent. This value is the ID of a portlet instance, and must match the value of one of the <computeroutput>&lt;instance-id&gt;</computeroutput> elements in the <filename>WEB-INF/portlet-instances.xml</filename> file. + </para> + </listitem> + <listitem> +<programlisting> +&lt;region&gt;...&lt;/region&gt; +&lt;height&gt;...&lt;/height&gt; +</programlisting> + <para> + The <computeroutput>&lt;region&gt;</computeroutput> and <computeroutput>&lt;height&gt;</computeroutput> elements define where the window appears within the page layout. The <computeroutput>&lt;region&gt;</computeroutput> element specifies where the window appears on the page. The <computeroutput>&lt;region&gt;</computeroutput> element often depends on other regions defined in the portal layout. The <computeroutput>&lt;height&gt;</computeroutput> element can be assigned a value between one and <replaceable>X</replaceable>. + </para> + </listitem> + <listitem> +<programlisting> +&lt;instance&gt; +</programlisting> + <para> + The <computeroutput>&lt;instance&gt;</computeroutput> element creates instances of portlets. The portlet will only be created and configured if the portlet is present, and if an instance with the same name does not already exist. + </para> + </listitem> + <listitem> +<programlisting> +&lt;instance-name&gt; +</programlisting> + <para> + The <computeroutput>&lt;instance-name&gt;</computeroutput> element maps to the <computeroutput>&lt;instance-ref&gt;</computeroutput> element. + </para> + </listitem> + <listitem> +<programlisting> +&lt;component-ref&gt; +</programlisting> + <para> + The <computeroutput>&lt;component-ref&gt;</computeroutput> element takes the name of the application, followed by the name of the portlet, as defined in the <filename>WEB-INF/portlet.xml</filename> file. + </para> + </listitem> + </itemizedlist> +</para> +<para> + The <computeroutput>&lt;security-constraint&gt;</computeroutput> element is a container for <computeroutput>&lt;policy-permission&gt;</computeroutput> elements. The following is an example of the <computeroutput>&lt;security-constraint&gt;</computeroutput> and <computeroutput>&lt;policy-permission&gt;</computeroutput> elements: +</para> +<para> +<programlisting><![CDATA[ +<security-constraint> + <policy-permission> + <role-name>User</role-name> + <action-name>view</action-name> + </policy-permission> +</security-constraint> + +<security-constraint> + <policy-permission> + <unchecked/> + <action-name>view</action-name> + </policy-permission> +</security-constraint>]]> +</programlisting> +</para> +<para> +<programlisting> +&lt;action-name&gt; +</programlisting> + </para> + <para> + The <computeroutput>&lt;action-name&gt;</computeroutput> element defines the access rights given to the role defined. Accepted values are: + </para> + <para> + <itemizedlist> + <listitem> + <para> + <computeroutput>view</computeroutput>: users can view the page. + </para> + </listitem> + <listitem> + <para> + <computeroutput>viewrecursive</computeroutput>: users can view the page and child pages. + </para> + </listitem> + <listitem> + <para> + <computeroutput>personalize</computeroutput>: users are able personalize the page's theme. + </para> + </listitem> + <listitem> + <para> + <computeroutput>personalizerecursive</computeroutput>: users are able personalize the page and child pages themes. + </para> + </listitem> + </itemizedlist> + </para> + <para> +<programlisting> +&lt;unchecked/&gt; +</programlisting> + </para> + <para> + If present, the <computeroutput>&lt;unchecked&gt;</computeroutput> element defines that anyone can view the instance. + </para> + <para> +<programlisting> +&lt;role-name&gt; +</programlisting> + </para> + <para> + The <computeroutput>&lt;role-name&gt;</computeroutput> element defines a role that the security constraint will apply to. The following example only allows users that are part of the <computeroutput>EXAMPLEROLE</computeroutput> role to access the instance: + </para> + <para> +<programlisting> +&lt;role-name&gt;EXAMPLEROLE&lt;/role-name&gt; +</programlisting> + </para> + </section> + <section id="desc_example_portal"> + <title>Defining a new Portal Instance</title> + <para> + The sample application descriptor in this section creates a new portal instance, <computeroutput>HelloPortal</computeroutput>, that contains two pages. To illustrate this example, download the <ulink url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles... portlet. To use the HelloWorldPortal portlet: + </para> + <para> + <orderedlist> + <listitem> + <para> + Download the <ulink url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles... portlet. + </para> + </listitem> + <listitem> + <para> + Unzip the <filename>HelloWorldPortal</filename> ZIP file. + </para> + </listitem> + <listitem> + <para> + To expand the WAR file, which gives you access to the XML descriptors, change into the <filename>HelloWorldPortal/</filename> directory, and run the <command>ant explode</command> command. + </para> + </listitem> + <listitem> + <para> + If you did not expand the <filename>helloworldportal.war</filename> file, copy the <filename>helloworldportal.war</filename> file into the correct JBoss AS or JBoss EAP <filename>deploy/</filename> directory. If you expanded the <filename>helloworldportal.war</filename> file, copy the <filename>HelloWorldPortal/output/lib/exploded/helloworldportal.war/</filename> directory into the correct JBoss AS or JBoss EAP <filename>deploy/</filename> directory. For example, if you are using the <computeroutput>default</computeroutput> JBoss AS profile, copy the WAR file or the expanded directory into the <filename>$JBOSS_HOME/server/default/deploy/</filename> directory. + </para> + </listitem> + </orderedlist> + </para> + <para> + The HelloWorldPortal portlet is hot-deployable, so the JBoss EAP or JBoss AS server does not have to be restarted after deploying the HelloWorldPortal portlet. The following is an example of the <filename>HelloWorldPortal/WEB-INF/helloworld-object.xml</filename> descriptor: + </para> + <para> +<programlisting><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE deployments PUBLIC + "-//JBoss Portal//DTD Portal Object 2.6//EN" + "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd"> +<deployments> + <deployment> + <parent-ref/> + <if-exists>overwrite</if-exists> + <portal> + <portal-name>HelloPortal</portal-name> + <supported-modes> + <mode>view</mode> + <mode>edit</mode> + <mode>help</mode> + </supported-modes> + <supported-window-states> + <window-state>normal</window-state> + <window-state>minimized</window-state> + <window-state>maximized</window-state> + </supported-window-states> + <properties> + <!-- Set the layout for the default portal --> + <!-- see also portal-layouts.xml --> + <property> + <name>layout.id</name> + <value>generic</value> + </property> + <!-- Set the theme for the default portal --> + <!-- see also portal-themes.xml --> + <property> + <name>theme.id</name> + <value>renaissance</value> + </property> + <!-- set the default render set name (used by the render tag in layouts) --> + <!-- see also portal-renderSet.xml --> + <property> + <name>theme.renderSetId</name> + <value>divRenderer</value> + </property> + </properties> + <security-constraint> + <policy-permission> + <action-name>personalizerecursive</action-name> + <unchecked/> + </policy-permission> + </security-constraint> + <page> + <page-name>default</page-name> + <security-constraint> + <policy-permission> + <action-name>viewrecursive</action-name> + <unchecked/> + </policy-permission> + </security-constraint> + <window> + <window-name>MyPortletWindow</window-name> + <instance-ref>MyPortletInstance</instance-ref> + <region>center</region> + <height>0</height> + </window> + </page> + </portal> + </deployment> + <deployment> + <parent-ref>HelloPortal</parent-ref> + <if-exists>overwrite</if-exists> + <page> + <page-name>foobar</page-name> + <security-constraint> + <policy-permission> + <action-name>viewrecursive</action-name> + <unchecked/> + </policy-permission> + </security-constraint> + <window> + <window-name>MyPortletWindow</window-name> + <instance-ref>MyPortletInstance</instance-ref> + <region>center</region> + <height>0</height> + </window> + </page> + </deployment> +</deployments>]]> +</programlisting> + </para> + <para> + When deployed, this example registers a new portal instance, <computeroutput>HelloPortal</computeroutput>, that contains two pages. To view the default page in the <computeroutput>HelloPortal</computeroutput> instance, navigate to <ulink url="http://localhost:8080/portal/portal/HelloPortal"/>, and for the second page, <ulink url="http://localhost:8080/portal/portal/HelloPortal/foobar"/>. + </para> + <para> + <note> + <title>Portal Instance <computeroutput>default</computeroutput> Page</title> + <para> + For a portal instance to be accessible via a Web browser, you must define a default page. + </para> + </note> + </para> + </section> + </section> +</chapter> + <chapter id="urls"> + <!--<chapterinfo> + <author> + <firstname>Julien</firstname> + <surname>Viet</surname> + </author> + <author> + <firstname>Thomas</firstname> + <surname>Heute</surname> + </author> + <author> + <firstname>Roy</firstname> + <surname>Russo</surname> + </author> + </chapterinfo>--> + <title>Portal URLs</title> + <section> + <title>Introduction to Portals</title> + <para> + Portal URLs are often very complicated; however, it is possible to setup entry points in portals that follow simple patterns. + </para> + <para> + Each portal container can contain multiple portals. Within a given portal, windows are organized into pages, with a page being a collection of windows associated to a name: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/tutorials/SpecPortalDef.png" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + <para> + Before reading the following sections, be familiar with how to define pages and portal. Refer to <xref linkend="desc_example_page"/> for details. + </para> + </section> + <section> + <title>Accessing a Portal</title> + <para> + The <computeroutput>default</computeroutput> portal is used when no portal is specified. How selection is done: + </para> + + <itemizedlist> + <listitem> + <para> + <computeroutput>/portal/</computeroutput> points to the default page of the default portal. + </para> + </listitem> + <listitem> + <para> + <computeroutput>/portal/<replaceable>portal-name</replaceable>/</computeroutput> points to the default page of the <replaceable>portal-name</replaceable> portal. + </para> + </listitem> + </itemizedlist> + + <note><title>Note</title><para>The default page or portal can be specified either by using the admin portlet or by using the XML descriptors as explained in the <xref linkend="xml.default.objectname.property"/>.</para></note> + + + </section> + <section> + <title>Accessing a Page</title> + <para> + Each portal can have multiple pages, with each portal having a default page. When a portal is selected, a page must be used, and all windows in that page are rendered. The page selection mechanism is as follows: + </para> + <para> + <computeroutput>/portal/default/<replaceable>page-name</replaceable></computeroutput> renders the <replaceable>page-name</replaceable> page. + </para> + </section> + <section> + <title>Accessing CMS Content</title> + <para> + The <emphasis>CMSPortlet</emphasis> delivers content transparently, without modifying the displayed URL. It is desirable to display binary content, such as GIF, JPEG, PDF, ZIP, and so on, outside of the confines of the portal. For example, <computeroutput>/content/default/images/jboss_logo.gif</computeroutput> displays the <computeroutput>jboss_logo.gif</computeroutput> file outside of the portal. + </para> + <para> + To display content outside of the portal, the portal interprets any path beginning with <computeroutput>/content</computeroutput> as a request for CMS content. As long as the <computeroutput>&lt;mime-type&gt;</computeroutput> is not <computeroutput>text/html</computeroutput>, or <computeroutput>text/text</computeroutput>, and the path to the content begins with <computeroutput>/content</computeroutput>, the content is rendered independently, outside of the portal. + </para> + </section> + <!-- + <section> + <title>Advanced portal urls</title> + <para>JBoss Portal can consume and produce URLs in a very flexible manner. Consuming means + that an URL is accepted by the portal, translated into some action and send a response to the + browser. Producing means to create an URL for a particular action when the portal needs one. + This part is an advanced topic explaining the internal mechanisms developped in JBoss Portal to + produce and consumer URLs. It should be readen with care as it exposes internals of JBoss Portal + that may change in later releases of the product.</para> + <para>JBoss Portal url handling mechanism is based on several design patterns.</para> + <section> + <title>Portal Commands</title> + <para></para> + </section> + <section> + <title>Portal urls</title> + <para>At runtime portal commands are converted back and forth into portal urls. Creation + of urls and decoding of urls is now known at compile time, otherwise that would lead + to a very inflexible portal since changing the behavior would imply to update the source + code and recompile the portal, that would not be an acceptable solution. There is + a well known design pattern which provides an elegant and powerful solution to this problem and + is called Chain of Responsibility.</para> + <para>Portal commands have a state which parameterizes them. For instance there is a command + called <emphasis>ViewPageCommand</emphasis> which displays a portal page in the browser. The state + of that command consist in the id of the page. There is a bidirectionnal mapping between portal urls + and portal commands. Portal commands are created from URL using a service called <emphasis>CommandFactory</emphasis>, + which takes a request object and provides a portal command. Conversely, portal urls are created from + portal commands using a service called <emphasis>URLFactory</emphasis>.</para> + <para>The task of decoding urls is performed by a set of command factories which are wired + together in the configuration file. We can dist</para> + </section> + </section> + --> +</chapter> + <chapter id="coordination"> + <!--<chapterinfo> + <author> + <firstname>Boleslaw</firstname> + <surname>Dawidowicz</surname> + </author> + </chapterinfo>--> + <title>JBoss Portal Explicit Coordination</title> + <section> + <title>Explicit vs implicit coordination</title> + <para> + Portlet 2.0 coordination features are mediated by the portal between several + portlet windows, therefore the portal at runtime needs to be able to define + relationships between windows. Relationship can be established from an implicit + model (i.e a set of predicates applied on some state that will answer TRUE/FALSE + to the question are the portlet windows foo and bar in a relationship) or from an + explicit model (that states that foo and bar have a relationship). The implicit + model is very good for defining default configuration as it does not require much + configuration but is not able to cover the exceptional case, that's why we need + to combine it with an explicit model that will take precedence over the implicit + model, it is the well known principle of convention over configuration. + </para> + <para> + Currently all explicit coordination happens only in the scope of the same page. + </para> + </section> + <section> + <title>Bindings and wirings</title> + + <section> + <title>Event wiring</title> + + <para> + Wires JSR-286 events. With implicit wirings the event producer and the + consumer declares the same event namespace and local name to get event + delivered in the scope of the same page. With explicit wiring any pairs of + Window:Event can be connected. + </para> + </section> + <section> + <title>Parameter binding</title> + + <para> + Binds JSR-286 shared parameters. With implicit binding parameters with the + same public name are shared. With explicit binding any public parameters can + share values. Windows for which such binding applies are explicitly defined. + </para> + </section> + <section> + <title>Alias binding</title> + + <para> + Explicit alias binding define a name of page scoped parameter that will apply + value to specified portlet windows public parameters. + </para> + + <programlisting><![CDATA[http://localhost:8080/portal/portal/default/Coordination+Samples?aliasBinding1=someValue]]></programlisting> + </section> + </section> + <section> + <title>Coordination configuration</title> + + <para> + Configuration takes place in -object.xml file. The &lt;coordination&gt; tag + can be used in both &lt;page&gt; and &lt;portal&gt; tags. When used in + &lt;portal&gt; tag only &lt;implicit-mode&gt; tag can be defined for wirings + and bindings: + </para> + + <programlisting role="XML"><![CDATA[<portal> + + ... + + <coordination> + <bindings> + <implicit-mode>TRUE</implicit-mode> + </bindings> + <wirings> + <implicit-mode>FALSE</implicit-mode> + </wirings> + </coordination> + +</portal>]]></programlisting> + <para> + When used within the &lt;page&gt; tag coordination event wirings and bindings + can be defined:&lt;/page&gt;</para> + + <programlisting role="XML"><![CDATA[<coordination> + + <wirings> + <implicit-mode>TRUE</implicit-mode> + <event-wiring> + <name>eventWiring1</name> + <sources> + <window-coordination> + <window-name>ShoppingCatalogPortletWindow1</window-name> + <qname>{urn:jboss:portal:samples:event}CartEvent</qname> + </window-coordination> + </sources> + <destinations> + <window-coordination> + <window-name>ShoppingCartPortletWindow2</window-name> + <qname>{urn:jboss:portal:samples:event}CartEvent</qname> + </window-coordination> + <window-coordination> + <window-name>ShoppingCartPortletWindow3</window-name> + <qname>{urn:jboss:portal:samples:event}CartEvent</qname> + </window-coordination> + </destinations> + </event-wiring> + <event-wiring> + <name>eventWiring2</name> + <sources> + <window-coordination> + <window-name>ShoppingCatalogPortletWindow2</window-name> + <qname>{urn:jboss:portal:samples:event}CartEvent</qname> + </window-coordination> + </sources> + <destinations> + <window-coordination> + <window-name>ShoppingCartPortletWindow1</window-name> + <qname>{urn:jboss:portal:samples:event}CartEvent</qname> + </window-coordination> + <window-coordination> + <window-name>ShoppingCartPortletWindow4</window-name> + <qname>{urn:jboss:portal:samples:event}CartEvent</qname> + </window-coordination> + </destinations> + </event-wiring> + </wirings> + + + <bindings> + <implicit-mode>FALSE</implicit-mode> + + <parameter-binding> + <id>parameterBinding1</id> + <window-coordination> + <window-name>SomePortletWindow1</window-name> + <qname>foo</qname> + </window-coordination> + <window-coordination> + <window-name>SomePortletWindow2</window-name> + <qname>foo</qname> + </window-coordination> + <window-coordination> + <window-name>SomePortletWindow3</window-name> + <qname>foo</qname> + </window-coordination> + </parameter-binding> + + <parameter-binding> + <id>parameterBinding2</id> + <window-coordination> + <window-name>SomePortletWindow1</window-name> + <qname>bar1</qname> + </window-coordination> + <window-coordination> + <window-name>SomePortletWindow2</window-name> + <qname>{urn:jboss:portal:samples:daa1}daa1</qname> + </window-coordination> + </parameter-binding> + + <alias-binding> + <id>aliasBinding1</id> + <qname>foo</qname> + </alias-binding> + + <alias-binding> + <id>aliasBinding2</id> + <qname>bar1</qname> + <qname>{urn:jboss:portal:samples:daa2}daa2</qname> + </alias-binding> + + </bindings> +</coordination>]]></programlisting> + + <section> + <title>&lt;implicit-mode&gt;</title> + + <para> + This tag can be applied for both &lt;bindings&gt; and &lt;wirings&gt; + tags. It defines if implicit coordination is enabled or disabled for + this given portal object. Value of this setting is cascaded to all + children in portal object tree unless overwritten somewhere in the + hierarchy. If no &lt;implicit-mode&gt; is defined in portal object tree + default value is TRUE. + </para> + </section> + </section> + <section> + <title>Coordination Samples</title> + <para> + JBoss Portal comes with several examples in 'Coordination Samples' page. Its good + to follow them looking at the configuration file that can be found in + portal-coordination-samples.war/WEB-INF/default-object.xml + </para> + </section> +</chapter> + <chapter id="errorhandling"> + <!-- <chapterinfo> + <author> + <firstname>Julien</firstname> + <surname>Viet</surname> + </author> + </chapterinfo>--> + <title>Error Handling Configuration</title> + <para> + The JBoss Portal request pipeline allows fine-grained, dynamic configuration of how JBoss Portal behaves when errors occur during runtime. + </para> + <section> + <title>Error Types</title> + <para>There are several types of errors that can occur during a request: + <itemizedlist> + <listitem> + <para> + <emphasis>Access denied</emphasis>: the user does not have the required permissions to access the resource. + </para> + </listitem> + <listitem> + <para> + <emphasis>Error</emphasis>: an anticipated error, such as when a portlet throws an exception. + </para> + </listitem> + <listitem> + <para> + <emphasis>Internal error</emphasis>: an unexpected error. + </para> + </listitem> + <listitem> + <para> + <emphasis>Resource not found</emphasis>: the resource was not found. + </para> + </listitem> + <listitem> + <para> + <emphasis>Resource unavailable</emphasis>: the resource was found, but was not serviceable. + </para> + </listitem> + </itemizedlist> + </para> + </section> + <section> + <title>Control Policies</title> + <para>If an error occurs, the request control-flow changes according to the configuration. This configuration is known as the <emphasis>control policy</emphasis>. + </para> + <section> + <title>Policy Delegation and Cascading</title> + <para> + When a control policy is invoked, the response sent by the control flow can be changed. If the control policy ignores the error, the error is handled by the next policy. If the control policy provides a new response, the next policy is not invoked, since the new response is not an error. + </para> + <para> + If a portlet in a page produces an exception, the following reactions are possible: + </para> + <para> + <itemizedlist> + <listitem> + <para> + the error is displayed in the window. + </para> + </listitem> + <listitem> + <para> + the window is removed from the aggregation. + </para> + </listitem> + <listitem> + <para> + a portal error page is displayed. + </para> + </listitem> + <listitem> + <para> + a HTTP 500 error response is sent to the Web browser. + </para> + </listitem> + </itemizedlist> + </para> + </section> + <section> + <title>Default Policy</title> + <para>The default policy applies when errors are not handled by another level. By default, errors are translated + into the most appropriate HTTP response: + </para> + <para> + <itemizedlist> + <listitem> + <para> + Access denied: <computeroutput>HTTP 403 Forbidden</computeroutput> + </para> + </listitem> + <listitem> + <para> + Error: <computeroutput>HTTP 500 Internal Server Error</computeroutput> + </para> + </listitem> + <listitem> + <para> + Internal error: <computeroutput>HTTP 500 Internal Server Error</computeroutput> + </para> + </listitem> + <listitem> + <para> + Resource not found: <computeroutput>HTTP 404 Not Found</computeroutput> + </para> + </listitem> + <listitem> + <para> + Resource unavailable: <computeroutput>HTTP 404 Not Found</computeroutput> + </para> + </listitem> + </itemizedlist> + </para> + </section> + <section> + <title>Portal Policy</title> + <para> + The portal error-policy controls the response sent to the Web browser when an error occurs. A default error policy exists, which can be configured per portal. If an error occurs, the policy can either handle a redirect to a JSP page, or ignore it. If the error is ignored, it is handled by the default policy, otherwise a JSP page is invoked with the appropriate request attributes, allowing page customization. + </para> + </section> + <section> + <title>Page Policy</title> + <para> + The window error-policy controls how pages react to aggregation errors. Most of the time pages are an aggregation of several portlet windows, and the action to take when an error occurs differs from other policies. When an error occurs, the policy can either handle it, or ignore it. If the error is ignored, it is handled by the portal policy. Possible actions taken after such errors are: + </para> + <para> + <itemizedlist> + <listitem> + <para> + remove the window from the aggregation. + </para> + </listitem> + <listitem> + <para> + replace the markup of the window using a redirect to a JSP page. + </para> + </listitem> + </itemizedlist> + </para> + </section> + </section> + <section> + <title>Configuration using XML Descriptors</title> + <para> + Different policies are configured using portal object properties, allowing the error-handling policy for objects to be configured in XML descriptors -- the <filename>*-object.xml</filename> files -- for a portal deployment. + </para> + <section> + <title>Portal Policy Properties</title> + <para> + A set of properties configure the the behavior of the portal policy. These properties are only taken into account for objects that use the <emphasis>portal</emphasis> type. The following table represents possible portal-policy properties: + </para> + + <table frame="all"><title/> + <tgroup cols="3" align="left" colsep="1"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <colspec colname="c3"/> + <thead> + <row> + <entry align="center">Property Name</entry> + <entry align="center">Description</entry> + <entry align="center">Possible Values</entry> + </row> + </thead> + <tbody> + <row> + <entry align="center"><computeroutput>control.portal.access_denied</computeroutput></entry> + <entry align="center">when access is denied</entry> + <entry align="center"><computeroutput>ignore</computeroutput> and <computeroutput>jsp</computeroutput></entry> + </row> + <row> + <entry align="center"><computeroutput>control.portal.unavailable</computeroutput></entry> + <entry align="center">when a resource is unavailable</entry> + <entry align="center"><computeroutput>ignore</computeroutput> and <computeroutput>jsp</computeroutput></entry> + </row> + <row> + <entry align="center"><computeroutput>control.portal.not_found</computeroutput></entry> + <entry align="center">when a resource is not found</entry> + <entry align="center"><computeroutput>ignore</computeroutput> and <computeroutput>jsp</computeroutput></entry> + </row> + <row> + <entry align="center"><computeroutput>control.portal.internal_error</computeroutput></entry> + <entry align="center">when an unexpected error occurs</entry> + <entry align="center"><computeroutput>ignore</computeroutput> and <computeroutput>jsp</computeroutput></entry> + </row> + <row> + <entry align="center"><computeroutput>control.portal.error</computeroutput></entry> + <entry align="center">when an expected error occurs</entry> + <entry align="center"><computeroutput>ignore</computeroutput> and <computeroutput>jsp</computeroutput></entry> + </row> + <row> + <entry align="center"><computeroutput>control.portal.resource_uri</computeroutput></entry> + <entry align="center">the path to the JSP used for redirections</entry> + <entry align="center">a valid path to a JSP located in the <filename>portal-core.war/</filename> directory</entry> + </row> + </tbody> + </tgroup> + </table> + + + <para> + The following portal configuration demonstrates the use of portal-policy properties: + </para> + <para> +<programlisting><![CDATA[ +<portal> + <portal-name>MyPortal</portal-name> + ... + <properties> + <property> + <name>control.portal.access_denied</name> + <value>ignore</value> + </property> + <property> + <name>control.portal.unavailable</name> + <value>ignore</value> + </property> + <property> + <name>control.portal.not_found</name> + <value>ignore</value> + </property> + <property> + <name>control.portal.internal_error</name> + <value>jsp</value> + </property> + <property> + <name>control.portal.error</name> + <value>jsp</value> + </property> + <property> + <name>control.portal.resource_uri</name> + <value>/WEB-INF/jsp/error/portal.jsp</value> + </property> + ... + </properties> + ... +</portal> +]]></programlisting> + </para> + </section> + <section> + <title>Page Policy Properties</title> + <para> + A set of properties configure the behavior of the page policy. These properties are only taken into account for objects that use the <emphasis>portal</emphasis> type. The following table represents possible page-policy properties: + </para> + <para> + <table frame="all"><title/> + <tgroup cols="3" align="left" colsep="1"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <colspec colname="c3"/> + <thead> + <row> + <entry align="center">Property name</entry> + <entry align="center">Description</entry> + <entry align="center">Possible values</entry> + </row> + </thead> + <tbody> + <row> + <entry align="center"><computeroutput>control.page.access_denied</computeroutput></entry> + <entry align="center">when access is denied</entry> + <entry align="center"><computeroutput>ignore</computeroutput>, <computeroutput>jsp</computeroutput> and <computeroutput>hide</computeroutput></entry> + </row> + <row> + <entry align="center"><computeroutput>control.page.unavailable</computeroutput></entry> + <entry align="center">when a resource is unavailable</entry> + <entry align="center"><computeroutput>ignore</computeroutput>, <computeroutput>jsp</computeroutput> and <computeroutput>hide</computeroutput></entry> + </row> + <row> + <entry align="center"><computeroutput>control.page.not_found</computeroutput></entry> + <entry align="center">when a resource is not found</entry> + <entry align="center"><computeroutput>ignore</computeroutput>, <computeroutput>jsp</computeroutput> and <computeroutput>hide</computeroutput></entry> + </row> + <row> + <entry align="center"><computeroutput>control.page.internal_error</computeroutput></entry> + <entry align="center">when an unexpected error occurs</entry> + <entry align="center"><computeroutput>ignore</computeroutput>, <computeroutput>jsp</computeroutput> and <computeroutput>hide</computeroutput></entry> + </row> + <row> + <entry align="center"><computeroutput>control.page.error</computeroutput></entry> + <entry align="center">when an expected error occurs</entry> + <entry align="center"><computeroutput>ignore</computeroutput>, <computeroutput>jsp</computeroutput> and <computeroutput>hide</computeroutput></entry> + </row> + <row> + <entry align="center"><computeroutput>control.page.resource_uri</computeroutput></entry> + <entry align="center">the path to the JSP used for redirections</entry> + <entry align="center"><computeroutput>ignore</computeroutput>, <computeroutput>jsp</computeroutput> and <computeroutput>hide</computeroutput></entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para> + The following page configuration demonstrates the use of page-policy properties: + </para> + <para> +<programlisting><![CDATA[ +<page> + <page-name>MyPortal</page-name> + ... + <properties> + <property> + <name>control.page.access_denied</name> + <value>hide</value> + </property> + <property> + <name>control.page.unavailable</name> + <value>hide</value> + </property> + <property> + <name>control.page.not_found</name> + <value>hide</value> + </property> + <property> + <name>control.page.internal_error</name> + <value>jsp</value> + </property> + <property> + <name>control.page.error</name> + <value>jsp</value> + </property> + <property> + <name>control.page.resource_uri</name> + <value>/WEB-INF/jsp/error/page.jsp</value> + </property> + ... + </properties> + ... +</page> +]]></programlisting> + </para> + <para> + <note> + <title>Page Property Inheritance for Objects</title> + <para> + When page properties are configured for objects that use the <emphasis>portal</emphasis> type, the properties are inherited by pages in that portal. + </para> + </note> + </para> +</section> + </section> + <section> + <title>Using <trademark class="trade">JSP</trademark> to Handle Errors</title> + <para> + As described in previous sections, error handling can be redirected to a <trademark class="trade">JSP</trademark> page. Two pages can be created to handle errors: one for the portal level, and the other for the page level. Portal level error-handling requires a page that produces a full page, and page-level handling requires a page that produces markup, but only for a window. When the page is invoked, a set of request attributes are passed. The following table represents possible request attributes: + </para> + <para> + <table frame="all"><title/> + <tgroup cols="3" align="left" colsep="1"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <colspec colname="c3"/> + <thead> + <row> + <entry align="center">Attribute Name</entry> + <entry align="center">Attribute Description</entry> + <entry align="center">Attribute Value</entry> + </row> + </thead> + <tbody> + <row> + <entry align="center"><computeroutput>org.jboss.portal.control.ERROR_TYPE</computeroutput></entry> + <entry align="center">the error type</entry> + <entry align="center">possible values are <computeroutput>ACCESS_DENIED</computeroutput>, <computeroutput>UNAVAILABLE</computeroutput>, <computeroutput>ERROR</computeroutput>, <computeroutput>INTERNAL_ERROR</computeroutput>, and <computeroutput>NOT_FOUND</computeroutput></entry> + </row> + <row> + <entry align="center"><computeroutput>org.jboss.portal.control.CAUSE</computeroutput></entry> + <entry align="center">a cause which is thrown, that can be null</entry> + <entry align="center">the object is a subclass of <computeroutput>java.lang.Throwable</computeroutput></entry> + </row> + <row> + <entry align="center"><computeroutput>org.jboss.portal.control.MESSAGE</computeroutput></entry> + <entry align="center">an error message that can be null</entry> + <entry align="center">text</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para> + <note> + <title><trademark class="trade">JSP</trademark> Location</title><para> + The JavaServer Pages must be located in the <filename>jboss-portal.sar/portal-core.war/</filename> web application.</para> + </note> + </para> + </section> + <section> + <title>Configuration using the Portal Management Application</title> + <para> + The error handling policy can be configured via the portal management application. To access the portal management application: + </para> + <para> + <orderedlist> + <listitem> + <para> + Use a Web browser to navigate to <ulink url="http://localhost:8080/portal"/>. + </para> + </listitem> + <listitem> + <para> + Click the <guibutton>Login</guibutton> button on the top right-hand of the welcome page, and log in as the <option>admin</option> user. + </para> + </listitem> + <listitem> + <para> + Click the <guibutton>Admin</guibutton> tab on the top right-hand of the welcome page. Four tabs will appear on the left-hand side of the page. + </para> + </listitem> + <listitem> + <para> + Click the <guibutton>Admin</guibutton> tab to open the portal management application, and then click the <guibutton>Portal Objects</guibutton> tab to display available portals. + </para> + </listitem> + </orderedlist> + </para> + <para> + Configuration options are available as part of the properties for each configuration level. You can specify the default error handling policy (at the root of the portal object hierarchy) for each portal, or each page, by clicking on the <guibutton>Properties</guibutton> button for each page or portal: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata fileref="images/errorhandling/errorHandling_management.png" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + <para> + As well, you can specify how dashboards should behave with respect to error handling, by clicking on the <guibutton>Dashboards</guibutton> tab in the portal management application: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata fileref="images/errorhandling/errorHandlingUI.png" align="center" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + <para> + The page specified with <computeroutput>On error redirect to this resource</computeroutput> is used when the <option>Redirect to the specified resource</option> action is selected for an error type, such as <computeroutput>When access to the page is denied</computeroutput>. After making changes, click the <guibutton>Update</guibutton> button for settings to take effect. + </para> + </section> +</chapter> + <chapter id="contentintegration"> +<!-- <chapterinfo> + <author> + <firstname>Julien</firstname> + <surname>Viet</surname> + </author> + <author> + <firstname>Thomas</firstname> + <surname>Heute</surname> + </author> + </chapterinfo>--> + <title>Content Integration</title> + <para>Since JBoss Portal 2.6 it is possible to provide an easy integration of content within the portal. Up to the 2.4 version + content integration had to be done by configuring a portlet to show some content from an URI and then place that + portlet on a page. The new content integration capabilities allows to directly configure a page window with the content URI by + removing the need to configure a portlet for that purpose.</para> + <note><title>Note</title><para>We do not advocate to avoid the usage portlet preferences, we rather advocate that content configuration managed at the portal level + simplifies the configuration: it helps to make content a first class citizen of the portal instead of having an intermediary + portlet that holds the content for the portal. The portlet preferences can still be used to configure how content is displayed + to the user.</para></note> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/content/before.png" scalefit="1"/> + </imageobject> + + </mediaobject> + <para>The portal uses portlets to configure content</para> + + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/content/after.png" scalefit="1"/> + </imageobject> + + </mediaobject> + <para>The portal references directly the content and use portlet to interact with content</para> + + <section> + <title>Window content</title> + <para>The content of a window is defined by + <itemizedlist> + <listitem><para>The content URI which is the resource that the window is pointing to. It is an arbitrary string that + the portal cannot interpret and is left up to the content provider to interpret.</para></listitem> + <listitem><para>The window content type which defines how the portal interpret the window content + <itemizedlist> + <listitem><para>The default content type is for portlets and has the value <emphasis>portlet</emphasis>. In this + case the content URI is the portlet instance id.</para></listitem> + <listitem><para>The CMS content type allows to integrate content from the CMS at the page and it has the value + <emphasis>cms</emphasis>. For that content type, the content URI is the CMS file path.</para></listitem> + </itemizedlist></para> + </listitem> + <listitem><para>The content parameters which are a set of additional key/value string pairs holding state that is interpreted + by the content provider.</para></listitem> + </itemizedlist> + </para> + <para>At runtime when the portal needs to render a window it delegates the production of markup to a content provider. + The portal comes with a preconfigured set of providers which handles the portlet and the cms content types. The most + natural way to plug a content provider in the portal is to use a JSR 286 Portlet. Based on a few carefully chosen conventions + it is possible to provide an efficient content integration with the benefit of using standards and without requiring + the usage of a proprietary API.</para> + </section> + <section> + <title>Content customization</title> + <para>Content providers must be able to allow the user or administrator to chose content from the external resource + it integrates in the portal in order to properly configure a portal window. A few interactions between the portal, the content + provider and the portal user are necessary to achieve that goal. Here again it is possible to provide content + customization using a JSR 286 Portlet. For that purpose two special portlet modes called + <emphasis>edit_content</emphasis> and <emphasis>select_content</emphasis> has been introduced. It signals to the portlet + that it is selecting or editing the content portion of the state of a portlet. <emphasis>select_content</emphasis> is + used to select a new content to put in a window while <emphasis>edit_content</emphasis> is used to modify the previously + defined content, often the two modes will display the same thing. The traditional edit mode is not used because the edit mode + is more targeted to configure how the portlet shows content to the end user rather than what content it shows.</para> +<mediaobject> +<imageobject> + <imagedata align="center" fileref="images/content/cms.png" scalefit="1"/> + </imageobject> +</mediaobject> + <para>Example of content customization - CMS Portlet</para> + </section> + <section> + <title>Content Driven Portlet</title> + <para>Portlet components are used to integrate content into the portal. It relies on a few conventions which allow + the portal and the portlet to communicate. + </para> + <section> + <title>Displaying content</title> + <para>At runtime the portal will call the portlet with the view mode when it displays content. It will send + information about the content to display using the public render parameter <emphasis>urn:jboss:portal:content uri</emphasis> to the portlet. Therefore the portlet has + just to read the render parameters and use them to properly display the content in the portlet. The public render parameters + values are the key/value pairs that form the content properties and the resource URI of the content to display.</para> + </section> + <section> + <title>Configuring content</title> + <para>As explained before, the portal will call the portlet using the <emphasis>edit_content</emphasis> mode. + In that mode the portlet and the portal will communicate using either action or render parameters. We have two use cases + which are: + <itemizedlist> + <listitem><para>The portal needs to configure a new content item for a new window. In that use case the portal will not send special + render parameters to the portlet and the initial set of render parameters will be empty. The portlet can + then use render parameters in order to provide navigation in the content repository. For example the portlet + can navigate the CMS tree and store the current CMS path in the render parameters. Whenever the portlet has decided + to tell the portal that content has been selected by the user it needs to trigger a JSR-286 event with the uri and eventual parameters as payload.</para> + </listitem> + <listitem><para>The second use case happens when the portal needs to edit existing content. In such situation + everything works as explained before except that the initial set of render parameters of the portlet + will be prepopulated with the content uri URI and parameters.</para></listitem> + </itemizedlist> + </para> + </section> + <section> + <title>Step by step example of a content driven portlet</title> + <para/> + <section> + <title>The Portlet skeleton</title> + <para>Here is the base skeleton of the content portlet. The FSContentDrivenPortlet shows the files which are + in the war file in which the portlet is deployed. The arbitrary name <emphasis>filesystem</emphasis> + will be the content type interpreted by the portlet. + </para> + <programlisting><![CDATA[ +public class FSContentDrivenPortlet extends GenericPortlet +{ + + /** The edit_content mode. */ + public static final PortletMode EDIT_CONTENT_MODE = new PortletMode("edit_content"); + + ... + +} +]]></programlisting> + </section> + <section> + <title>Overriding the dispatch method</title> + <para>First the <emphasis>doDispatch(RenderRequest req, RenderResponse resp)</emphasis> is overridden in order + to branch the request flow to a method that will take care of displaying the editor.</para> + <programlisting><![CDATA[ +protected void doDispatch(RenderRequest req, RenderResponse resp) + throws PortletException, PortletSecurityException, IOException +{ + if (EDIT_CONTENT_MODE.equals(req.getPortletMode())) + { + doEditContent(req, resp); + } + else + { + super.doDispatch(req, resp); + } +} +]]></programlisting> + </section> + <section> + <title>Utilities methods</title> + <para>The portlet also needs a few utilities methods which take care of converting content URI to a file + back and forth. There is also an implementation of a file filter that keep only text files and avoid the + WEB-INF directory of the war file for security reasons.</para> + <programlisting><![CDATA[ +protected File getFile(String contentURI) throws IOException +{ + String realPath = getPortletContext().getRealPath(contentURI); + if (realPath == null) + { + throw new IOException("Cannot access war file content"); + } + File file = new File(realPath); + if (!file.exists()) + { + throw new IOException("File " + contentURI + " does not exist"); + } + return file; +} +]]></programlisting> + <programlisting><![CDATA[ + protected String getContentURI(File file) throws IOException + { + String rootPath = getPortletContext().getRealPath("/"); + if (rootPath == null) + { + throw new IOException("Cannot access war file content"); + } + + // Make it canonical + rootPath = new File(rootPath).getCanonicalPath(); + + // Get the portion of the path that is significant for us + String filePath = file.getCanonicalPath(); + return filePath.length() >= + rootPath.length() ? filePath.substring(rootPath.length()) : null; + } +]]></programlisting> + <programlisting><![CDATA[ + private final FileFilter filter = new FileFilter() + { + public boolean accept(File file) + { + String name = file.getName(); + if (file.isDirectory()) + { + return !"WEB-INF".equals(name); + } + else if (file.isFile()) + { + return name.endsWith(".txt"); + } + else + { + return false; + } + } + }; +]]></programlisting> + </section> + <section> + <title>The editor</title> + <para>The editor is probably the longest part of the portlet. It tries to stay simple though and goes directly + to the point.</para> + <mediaobject> <imageobject> + <imagedata align="center" fileref="images/content/fs1.png" scalefit="1"/> + </imageobject></mediaobject> + <para>Content editor of FSContentDrivenPortlet in action</para> + <programlisting><![CDATA[ +protected void doEditContent(RenderRequest req, RenderResponse resp) + throws PortletException, PortletSecurityException, IOException +{ + String uri = req.getParameter("current_uri"); + if (uri == null) + { + // Get the uri value optionally provided by the portal + uri = req.getParameter("uri"); + } + + // Get the working directory directory + File workingDir = null; + String currentFileName = null; + if (uri != null) + { + workingDir = getFile(uri).getParentFile(); + currentFileName = getFile(uri).getName(); + } + else + { + // Otherwise try to get the current directory we are browsing, + // if no current dir exist we use the root + String currentDir = req.getParameter("current_dir"); + if (currentDir == null) + { + currentDir = "/"; + } + workingDir = getFile(currentDir); + } + + // Get the parent path + String parentPath = getContentURI(workingDir.getParentFile()); + + // Get the children of the selected file, we use a filter + // to retain only text files and avoid WEB-INF dir + File[] children = workingDir.listFiles(filter); + + // Configure the response + resp.setContentType("text/html"); + PrintWriter writer = resp.getWriter(); + + // + writer.print("Directories:<br/>"); + writer.print("<ul>"); + PortletURL choseDirURL = resp.createRenderURL(); + if (parentPath != null) + { + choseDirURL.setParameter("current_dir", parentPath); + writer.print("<li><a href=\"" + choseDirURL + "\">..</a></li>"); + } + for (int i = 0;i < children.length;i++) + { + File child = children[i]; + if (child.isDirectory()) + { + choseDirURL.setParameter("current_dir", getContentURI(child)); + writer.print("<li><a href=\"" + choseDirURL + "\">" + child.getName() + + "</a></li>"); + } + } + writer.print("</ul><br/>"); + + // + writer.print("Files:<br/>"); + writer.print("<ul>"); + PortletURL selectFileURL = resp.createActionURL(); + selectFileURL.setParameter("content.action.select", "select"); + for (int i = 0;i < children.length;i++) + { + File child = children[i]; + if (child.isFile()) + { + selectFileURL.setParameter("current_uri", getContentURI(child)); + if (child.getName().equals(currentFileName)) + { + writer.print("<li><b>" + child.getName() + "</b></li>"); + } + else + { + writer.print("<li><a href=\"" + selectFileURL + "\">" + child.getName() + "</a></li>"); + } + } + } + writer.print("</ul><br/>"); + + // + writer.close(); +} +]]></programlisting> + </section> + <section> + <title>Viewing content at runtime</title> + <para>Last but not least the portlet needs to implement the <emphasis>doView(RenderRequest req, RenderResponse resp)</emphasis> + method in order to display the file that the portal window wants to show.</para> + <programlisting><![CDATA[ +protected void doView(RenderRequest req, RenderResponse resp) + throws PortletException, PortletSecurityException, IOException +{ + // Get the URI provided by the portal + String uri = req.getParameter("uri"); + + // Configure the response + resp.setContentType("text/html"); + PrintWriter writer = resp.getWriter(); + + // + if (uri == null) + { + writer.print("No selected file"); + } + else + { + File file = getFile(uri); + FileInputStream in = null; + try + { + in = new FileInputStream(file); + FileChannel channel = in.getChannel(); + byte[] bytes = new byte[(int)channel.size()]; + ByteBuffer buffer = ByteBuffer.wrap(bytes); + channel.read(buffer); + writer.write(new String(bytes, 0, bytes.length, "UTF8")); + } + catch (FileNotFoundException e) + { + writer.print("No such file " + uri); + getPortletContext().log("Cannot find file " + uri, e); + } + finally + { + if (in != null) + { + in.close(); + } + } + } + + // + writer.close(); +} +]]></programlisting> + </section> + <section> + <title>Hooking the portlet into the portal</title> + + <mediaobject><imageobject> + <imagedata align="center" fileref="images/content/fs2.png" scalefit="1"/> + </imageobject></mediaobject> + +<para>Management portlet with <emphasis>filesystem</emphasis> content type enabled</para> + + <para>Finally we need to make the portal aware of the fact that the portlet can edit and interpret content. For that + we need a few descriptors. The <emphasis>portlet.xml</emphasis> descriptor will define our portlet, the + <emphasis>portlet-instances.xml</emphasis> will create a single instance of our portlet. The + <emphasis>web.xml</emphasis> descriptor will contain a servlet context listener that will hook the content + type in the portal content type registry.</para> + <para>First, we need to define the portlet's particular event and render parameters:</para> + <programlisting><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2... http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + version="2.0"> + + <portlet> + <description>File System Content Driven Portlet</description> + <portlet-name>FSContentDrivenPortlet</portlet-name> + <display-name>File System Content Driven Portlet</display-name> + <portlet-class>org.jboss.portal.core.samples.basic.FSContentDrivenPortlet</portlet-class> + <supports> + <mime-type>text/html</mime-type> + <portlet-mode>VIEW</portlet-mode> + <portlet-mode>EDIT_CONTENT</portlet-mode> + </supports> + <portlet-info> + <title>File Portlet</title> + <keywords>sample,test</keywords> + </portlet-info> + <supported-public-render-parameter>uri</supported-public-render-parameter> + <supported-publishing-event xmlns:x="urn:jboss:portal:content">x:select</supported-publishing-event> + </portlet> + + <public-render-parameter> + <identifier>uri</identifier> + <qname xmlns:c="urn:jboss:portal:content">c:uri</qname> + </public-render-parameter> + + <event-definition> + <qname xmlns:x="urn:jboss:portal:content">x:select</qname> + <value-type>java.lang.String</value-type> + </event-definition> + +</portlet-app> +]]></programlisting> + <para>Note that here we need to use a JSR-286 portlet, this portlet will use the event <emphasis>urn:jboss:portal:content select</emphasis> and have a payload of type + <emphasis>java.lang.String</emphasis>. This event will be used to tell the portal the URI selected by the user. This same portlet will also be in charge of + rendering the content based on that URI, it will then also need to access the public render parameter qualified with the name: <emphasis>urn:jboss:portal:content uri</emphasis>. + </para> + <para>The portlet.xml descriptor</para> + <programlisting><![CDATA[ +<deployments> + ... + <deployment> + <instance> + <instance-id>FSContentDrivenPortletInstance</instance-id> + <portlet-ref>FSContentDrivenPortlet</portlet-ref> + </instance> + </deployment> + ... +</deployments +]]></programlisting> + <para>The portlet-instances.xml descriptor</para> + <programlisting><![CDATA[ +<web-app> + ... + <context-param> + <param-name>org.jboss.portal.content_type</param-name> + <param-value>filesystem</param-value> + </context-param> + <context-param> + <param-name>org.jboss.portal.portlet_instance</param-name> + <param-value>FSContentDrivenPortletInstance</param-value> + </context-param> + <listener> + <listener-class>org.jboss.content.ContentTypeRegistration</listener-class> + </listener> + ... +</web-app> +]]></programlisting> + <para>The web.xml descriptor</para> + <warning><title>Caution</title><para>You don't need to add the listener class into your war file. As it is provided by the portal + it will always be available.</para></warning> + </section> + </section> + <!-- + <section> + <title>Passing parameters along the URI</title> + <para>In simple cases like in the example, it was enough to pass a URI, in some cases it can be helpful to pass + other parameters, to do so, instead of having a payload of type <emphasis>java.lang.String</emphasis>, + simply use the following class: <emphasis>org.jboss.portal.api.content.SelectedContent</emphasis>. + </para> + </para> + </section> + --> + </section> + <section> + <title>Configuring window content in deployment descriptor</title> + <para>How to create a portlet that will enable configuration of content at runtime has been covered above, however + it is also possible to configure content in deployment descriptors. With our previous example it would give + the following snippet placed in a <emphasis>*-portal.xml</emphasis> file: + </para> + <programlisting><![CDATA[ +<window> +<window-name>MyWindow</window-name> +<content> + <content-type>filesystem</content-type> + <content-uri>/dir1/foo.txt</content-uri> +</content> +<region>center</region> +<height>1</height> +</window> +]]></programlisting> + <mediaobject><imageobject> + <imagedata align="center" fileref="images/content/fs3.png"/> + </imageobject></mediaobject> + <para>Final effect - portal window with FSContentDrivenPortlet</para> + <note><title>Note</title><para>How to configure CMS file this way is covered in the CMS chapter: <xref linkend="configuration-cms_content"/></para></note> + </section> +</chapter> + <chapter id="widgets"> + <!-- <chapterinfo> + <author> + <firstname>Emanuel</firstname> + <surname>Muckenhuber</surname> + </author> + </chapterinfo>--> + <title>Widget Integration</title> + <section> + <title>Introduction</title> + <para>JBoss Portal supports the integration of Google gadgets and Netvibes (<ulink url="http://dev.netvibes.com/doc/uwa_specification">UWA</... compatible) + widgets out of the box. This integration allows you to display the content of the widget within a portlet. + Both types can be added in the administration interface by editing the 'Page Layout' of a page or in the configuration of the users dashboard + when selecting the appropriate 'Content type'. + </para> + </section> + <section> + <title>Widget portlet configuration</title> + <para>It is possible to modify certain behavior of caching and fetching widgets by changing the init-param values of the portlet.</para> + <para> + <itemizedlist> + <listitem> + <para><emphasis role="bold">connectionTimeout</emphasis>. + + Connection timeout used for the directory lookup in milliseconds. + </para> + </listitem> + <listitem> + <para><emphasis role="bold">widgetExpiration</emphasis>. + + Time in minutes for which a widget should be cached. After this time the cached widget information will be deleted and + fetched again when the information are needed. + </para> + </listitem> + <listitem> + <para><emphasis role="bold">queryExpiration</emphasis>. + + Times in minutes for which a directory query should be cached. After this time the cached query information will be deleted. + </para> + </listitem> + <listitem> + <para><emphasis role="bold">fetchWidgetsOnDirectoryLookup</emphasis>. + + This parameter defines if all widgets from a directory lookup should be fetched at the time of the query or not. + The default values is false. This means that widgets are only fetched on demand - when the information is really needed. + </para> + </listitem> + </itemizedlist> + </para> + <para> + The parameter for both widget types can be changed identically in either: + <itemizedlist> + <listitem><para><emphasis>jboss-portal.sar/portal-widget.war/WEB-INF/portlet.xml</emphasis> (for google gadgets)</para></listitem> + <listitem><para>or <emphasis>jboss-portal.sar/portal-widget-netvibes.war/WEB-INF/portlet.xml</emphasis> (for netvibes widgets).</para></listitem> + </itemizedlist> + </para> + <para> + <programlisting><![CDATA[... + <portlet> + ... + <init-param> + <name>connectionTimeout</name> + <value>5000</value> + </init-param> + <init-param> + <name>widgetExpiration</name> + <value>360</value> + </init-param> + <init-param> + <name>queryExpiration</name> + <value>60</value> + </init-param> + <init-param> + <name>fetchWidgetsOnDirectoryLookup</name> + <value>false</value> + </init-param> + ... + </portlet> +...]]></programlisting> + </para> + <para> + For Netvibes widgets it is also possible to define a init-param called <emphasis role="bold">defaultHeight</emphasis> to set a specific + default height if no height attribute is defined by the widget itself. The default value is 250. + </para> + </section> +</chapter> + <chapter id="portletmodes"> + <!-- <chapterinfo> + <author> + <firstname>Julien</firstname> + <surname>Viet</surname> + </author> + </chapterinfo>--> + <title>Portlet Modes</title> + <para>JBoss Portal supports the standard portlet modes defined by the JSR-168 specification which are <emphasis>view</emphasis>, + <emphasis>edit</emphasis> and <emphasis>help</emphasis>. In addition of that it also supports the <emphasis>admin</emphasis> + portlet mode. + </para> + <section> + <title>Admin Portlet Mode</title> + <para>The admin mode defines a mode for the portlet which allows the administration of the portlet. Access to this mode + is only granted to users having an appropriate role. In order to grant admin access to a portlet, the user must have a role which + grants him the <emphasis>admin</emphasis> action permission on the portlet instance. This can be done in the + instance deployment descriptor or using the administation portlet of the portal. </para> + <section> + <title>Portlet configuration</title> + <para>In order to be able to use the admin mode, the portlet must declare it in the portlet deployment descriptor.</para> + <programlisting><![CDATA[ +<portlet-app> + ... + <portlet> + ... + <supports> + <mime-type>text/html</mime-type> + <portlet-mode>admin</portlet-mode> + </supports> + ... + </portlet> + ... + <custom-portlet-mode> + <name>admin</name> + </custom-portlet-mode> + ... +</portlet-app> +]]></programlisting> + </section> + <section> + <title>Declarative instance security configuration</title> + <para>The following example shows the configuration of a portlet instance that grants the admin action permission + to the <emphasis>Admin</emphasis> security role. It also grants the view action permission to all users. + </para> +<programlisting><![CDATA[ +... +<instance> + <instance-id>ModePortletInstance</instance-id> + <portlet-ref>ModePortlet</portlet-ref> + <security-constraint> + <policy-permission> + <action-name>admin</action-name> + <role-name>Admin</role-name> + </policy-permission> + <policy-permission> + <action-name>view</action-name> + <unchecked/> + </policy-permission> + </security-constraint> +</instance> +... +]]></programlisting> + </section> + <section> + <title>Instance security configuration with the administration portlet</title> + <para>At runtime the security configuration section of the administration portlet can be used to grant or revoke + the admin access. It can be done by clicking the security action of the portlet instance and then use the + security editor.</para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/portletmodes/editor.png"/> + </imageobject> + </mediaobject> + <para>Edit the security instance configuration</para> + + </section> + </section> +</chapter> + <chapter id="portal_api"> +<!-- <chapterinfo> + <author> + <firstname>Julien</firstname> + <surname>Viet</surname> + </author> + <author> + <firstname>Thomas</firstname> + <surname>Heute</surname> + </author> + </chapterinfo>--> + <title>Portal API</title> + <section> + <title>Introduction</title> + + <para>JBoss Portal provides an Application Programming Interface (API) which allows to write code + that interacts with the portal. The life time and validity of the API is tied to the major version which means + that no changes should be required when code is written against the API provided by the JBoss Portal + 2.x versions and used in a later version of JBoss Portal 2.x.</para> + + <para>The Portal API package prefix is <emphasis>org.jboss.portal.api</emphasis>. All of the classes that are part + of this API are prefixed with this package name except for the <emphasis>org.jboss.portal.Mode</emphasis> + and <emphasis>org.jboss.portal.WindowState</emphasis> classes. These two classes were defined before the official + Portal API framework was created and so the names have been maintained for backward compatibility.</para> + <para>The Portlet API defines two classes that represent a portion of the visual state of a Portlet which + are <emphasis>javax.portlet.PortletMode</emphasis> and <emphasis>javax.portlet.WindowState</emphasis>. Likewise + the Portal API defines similar classes named <emphasis>org.jboss.portal.Mode</emphasis> and + <emphasis>org.jboss.portal.WindowState</emphasis> which offer comparable characteristics, the main differences are:</para> + + <itemizedlist> + <listitem><para>Usage of factory methods to obtain instances.</para></listitem> + <listitem><para>Classes implements the <emphasis>java.io.Serializable</emphasis> interface.</para></listitem> + </itemizedlist> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/portalapi/Mode.png"/> + </imageobject> + </mediaobject> + <para>The Mode class</para> + + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/portalapi/WindowState.png"/> + </imageobject> + + </mediaobject> + + <para>The WindowState class</para> + + <note><para>In the Portal API, the <emphasis>Mode</emphasis> interface is named like this because it does + represent the mode of some visual object. The Portlet API names it <emphasis>PortletMode</emphasis> because + it makes the assumption that the underlying object is of type Portlet.</para></note> + </section> + <section> + <title>Portlet to Portal communication</title> + <para>There are times when a portlet needs to signal the portal or share information with it. The portal is the only authority + to decide if it will take into account that piece of information or ignore it. In JBoss Portal we use as much as possible the + mechanisms offered by the portlet spec to achieve that communication.</para> + <section> + <title>Requesting a sign out</title> + <para> + If a portlet desires to sign out the user, it can let the portal know by triggering a JSR-286 portlet event. + To do so, simply defines the event "signOut" in the namespace "urn:jboss:portal" as a publishing event. + In the action phase of the portlet, trigger the event, as a payload you can specify a redirection URL. If the payload is null, + it will redirect the user to the default page of the default portal. + See the following snippet to use in the action phase, it will ask the portal to sign out the user and redirect him to the JBoss + Portal blog: + <programlisting role="java"><![CDATA[QName name = new QName("urn:jboss:portal", "signOut"); +response.setEvent(name, "http://blog.jboss-portal.org"); ]]></programlisting> + </para> + </section> + <section> + <title>Setting up the web browser title</title> + <para> + The JSR-286 specification introduced a new phase for setting up the HTML headers. It is commonly used to add stylesheets + and javascript to the page. An extension of it for JBoss Portal lets you define the web browser title. + To define the web browser title, a portlet simply needs to define a new header element "title". This could be done by a portlet overriding + the method <literal>doHeaders(RenderRequest req, RenderResponse resp)</literal> to add such an element. + <programlisting role="java"><![CDATA[public void doHeaders(RenderRequest req, RenderResponse resp) +{ + Element element = resp.createElement("title"); + element.setTextContent("My new web browser title"); + resp.addProperty(MimeResponse.MARKUP_HEAD_ELEMENT, element); +}]]></programlisting> + <warning><para>It several portlets on a page defines a web browser title, only one of them will be displayed. + We can consider that the title to be displayed will be randomly chosen.</para></warning> + </para> + </section> + </section> + <section> + <title>Portal URL</title> + <para>The Portal API defines the <emphasis>org.jboss.portal.api.PortalURL</emphasis> interface to represent + URL managed by the portal.</para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/portalapi/PortalURL.png"/> + </imageobject> + </mediaobject> + <para>The PortalURL interface</para> + + <itemizedlist> + <listitem><para>The <emphasis>setAuthenticated(Boolean wantAuthenticated)</emphasis> methods defines if the + URL requires the authentication of the user. If the argument value is true then the user must be authenticated + to access the URL, if the argument value is false then the user should not be authenticated. Finally if the argument value is + null then it means that the URL authenticated mode should reuse the current mode.</para></listitem> + <listitem><para>The <emphasis>setSecure(Boolean wantSecure)</emphasis> methods defines the same as above but for the + transport guarantee offered by the underlying protocol which means most of the time the secure HTTP protocol (HTTPS).</para></listitem> + <listitem><para>The <emphasis>setRelative(boolean relative)</emphasis> defines the output format of the URL and + whether the created URL will be an URL relative to the same web server or will be the full URL.</para></listitem> + <listitem><para>The <emphasis>toString()</emphasis> method will create the URL as a string.</para></listitem> + </itemizedlist> + </section> + <section> + <title>Portal session</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/portalapi/PortalSession.png"/> + </imageobject> + </mediaobject> + <para>The PortalSession interface</para> + + <para>It is possible to have access to a portion of the portal session to store objects. The <emphasis>org.jboss.portal.api.session.PortalSession</emphasis> + interface defines its API and is similar to the <emphasis>javax.servlet.http.HttpSession</emphasis> except that it does + not offer methods to invalidate the session as the session is managed by the portal. + </para> + </section> + + <section> + <title>Portal runtime context</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/portalapi/PortalRuntimeContext.png"/> + </imageobject> + </mediaobject> + <para>The PortalRuntimeContext interface</para> + + <para>The <emphasis>org.jboss.portal.api.PortalRuntimeContext</emphasis> gives access to state or operations + associated at runtime with the current user of the portal. The <emphasis>String getUserId()</emphasis> retrieve + the user id and can return null if no user is associated with the context. It also gives access to the + <emphasis>PortalSession</emphasis> instance associated with the current user. Finally it gives access to the + <emphasis>NavigationalStateContext</emphasis> associated with the current user.</para> + </section> + + <section> + <title>Portal nodes</title> + <para>The portal structure is a tree formed by nodes. It is possible to programmatically access the portal tree in order to + </para> + <itemizedlist> + <listitem><para>discover the tree structure of the portal</para></listitem> + <listitem><para>create URL that will render the different portal nodes</para></listitem> + <listitem><para>access the properties of a specific node</para></listitem> + </itemizedlist> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/portalapi/PortalNode.png"/> + </imageobject> + </mediaobject> + <para>The PortalNode interface</para> + + <para>As usual with tree structures, the main interface to study is the <emphasis>org.jboss.portal.api.node.PortalNode</emphasis>. That interface + is intentionally intended for obtaining useful information from the tree. It is not possible to use it to modify + the tree shape because it is not intended to be a management interface.</para> + <programlisting><![CDATA[ +public interface PortalNode +{ + int getType(); + String getName(); + String getDisplayName(Locale locale); + Map getProperties(); + PortalNodeURL createURL(PortalRuntimeContext portalRuntimeContext); + ... +} +]]></programlisting> + <para>The interface offers methods to retrieve informations for a given node such as the node type, the node name + or the properties of the node. The noticeable node types are:</para> + <itemizedlist> + <listitem><para>PortalNode.TYPE_PORTAL : the node represents a portal</para></listitem> + <listitem><para>PortalNode.TYPE_PAGE : the node represents a portal page</para></listitem> + <listitem><para>PortalNode.TYPE_WINDOW : the node represents a page window</para></listitem> + </itemizedlist> + <para>The <emphasis>org.jboss.portal.api.node.PortalNodeURL</emphasis> is an extension of the <emphasis>PortalURL</emphasis> interface + which adds additional methods useful for setting parameters on the URL. There are no guarantees that the + portal node will use the parameters. So far portal node URL parameters are only useful for nodes of type + <emphasis>PortalNode.TYPE_WINDOW</emphasis> and they should be treated as portlet render parameters in the case of + the portlet is a local portlet and is not a remote portlet. The method that creates portal node URL requires + as parameter an instance of <emphasis>PortalRuntimeContext</emphasis>.</para> + <para>The interface also offers methods to navigate the node hierarchy:</para> + <programlisting><![CDATA[ +public interface PortalNode +{ + ... + PortalNode getChild(String name); + Collection getChildren(); + PortalNode getRoot(); + PortalNode getParent(); + ... +} +]]></programlisting> + </section> + <section> + <title>Portal navigational state</title> + <para>The navigational state is a state managed by the portal that associates to each user the state triggered + by its navigation. A well known part of the navigational state are the render parameters provided at runtime + during the call of the method <emphasis>void render(RenderRequest req, RenderResponse resp)</emphasis>. The portal + API offers an interface to query and update the navigational state of the portal. For now the API only exposes + mode and window states of portal nodes of type window.</para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/portalapi/NavigationalStateContext.png"/> + </imageobject> + </mediaobject> + <para>The NavigationalStateContext interface</para> + + </section> + <section> + <title>Portal events</title> + <para>Portal events are a powerful mechanism to be aware of what is happening in the portal at runtime. The base + package for event is <emphasis>org.jboss.portal.api.event</emphasis> and it contains the common event classes + and interfaces. + </para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/portalapi/PortalEvent.png"/> + </imageobject> + </mediaobject> + <para>The PortalEvent class</para> + + <para>The <emphasis>org.jboss.portal.api.event.PortalEvent</emphasis> abstract class is the base class for + all kind of portal events. + </para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/portalapi/PortalEventContext.png"/> + </imageobject> + </mediaobject> + <para>The PortalEventContext interface</para> + + <para> + The <emphasis>org.jboss.portal.api.event.PortalEventContext</emphasis> interface defines the context in which + an event is created and propagated. It allows retrieval of the <emphasis>PortalRuntimeContext</emphasis> which + can in turn be used to obtain the portal context. + </para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/portalapi/PortalEventListener.png"/> + </imageobject> + </mediaobject> + <para>The PortalEventListener interface</para> + + <para> + The <emphasis>org.jboss.portal.api.event.PortalEventListener</emphasis> interface defines the contract that + class can implement in order to receive portal event notifications. It contains the method + <emphasis>void onEvent(PortalEvent event)</emphasis> called by the portal framework. + </para> + <para> + Listeners declaration requires a service to be deployed in JBoss that will instantiate the service implementation + and register it with the service registry. We will see how to achieve that in the example section of this chapter. + </para> + <note> + <para>The event propagation model uses one instance of a listener class to receive all portal events that + may be routed to that class when appropriate. Therefore implementors needs to be aware of that model + and must provide <emphasis role="bold">thread safe</emphasis> implementations.</para> + </note> + <section> + <title>Portal node events</title> + <para>Portal node events extend the abstract portal event framework in order to provide notifications + about user interface events happening at runtime. For instance when the portal renders a page or a window, + a corresponding event will be fired.</para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/portalapi/PortalNodeEvent.png" scalefit="1"/> + </imageobject> + </mediaobject> + <para>The portal node event class hierarchy</para> + + <para>The <emphasis>org.jboss.portal.api.node.event.PortalNodeEvent</emphasis> class extends the + <emphasis>org.jboss.portal.api.node.PortalEvent</emphasis> class and is the base class for all events + of portal nodes. It defines a single method <emphasis>PortalNode getNode()</emphasis> which can be + used to retrieve the node targetted by the event.</para> + <para>The <emphasis>org.jboss.portal.api.node.event.WindowEvent</emphasis> is an extension for portal nodes + of type window. It provides access to the mode and window state of the window. It has 3 subclasses which + represent different kind of event that can target windows.</para> + <para>The <emphasis>org.jboss.portal.api.node.event.WindowNavigationEvent</emphasis> is fired when the + window navigational state changes. For a portlet it means that the window is targetted by an URL of type + render.</para> + <para>The <emphasis>org.jboss.portal.api.node.event.WindowActionEvent</emphasis> is fired when the + window is targetted by an action. For a portlet it means that the window is targetted by an URL of type + action.</para> + <para>The <emphasis>org.jboss.portal.api.node.event.WindowRenderEvent</emphasis> is fired when the + window is going to be rendered by the portal.</para> + <para>The <emphasis>org.jboss.portal.api.node.event.PageEvent</emphasis> is an extension for portal nodes + of type page.</para> + <para>The <emphasis>org.jboss.portal.api.node.event.PageRenderEvent</emphasis> is fired when the + page is going to be rendered by the portal.</para> + <section> + <title>Portal node event propagation model</title> + <para> + A portal node event is fired when an event of interest happens to a portal node of the portal tree. The + notification model is comparable to the <ulink url="http://en.wikipedia.org/wiki/DOM_Events#Event_flow">bub... propagation model </ulink> + defined by the DOM specification. When an event is fired, the event is propagated in the hierarchy from the most + inner node where the event happens to the root node of the tree. + </para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/portalapi/eventpropagation.png"/> + </imageobject> + </mediaobject> + <para>The portal node event propagation model</para> + + + </section> + <section> + <title>Portal node event listener</title> + <para>The <emphasis>org.jboss.portal.api.node.event.PortalNodeEventListener</emphasis> interface should + be used instead of the too generic <emphasis>org.jboss.portal.api.event.PortalEventListener</emphasis> when + it comes down of listening portal node events. Actually it does not replace it, the <emphasis>PortalEventListener</emphasis> + interface semantic allows only traditional event delivering. The <emphasis>PortalNodeEventListener</emphasis> + interface is designed to match the bubbling effect during an event delivery.</para> + <para>The <emphasis>PortalNodeEvent onEvent(PortalNodeEventContext context, PortalNodeEvent event)</emphasis> + method declares a <emphasis>PortalNodeEvent</emphasis> as return type. Commonly the method returns null; + however, a returned PortalNodeEvent replaces the event in the listeners subsequently called during + the event bubbling process. + </para> + </section> + <section> + <title>Portal node event context</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/portalapi/PortalNodeEventContext.png"/> + </imageobject> + </mediaobject> + <para>The PortalNodeEventContext interface</para> + + <para>The <emphasis>org.jboss.portal.api.node.event.PortalNodeEventContext</emphasis> interface extends + the <emphasis>PortalEventContext</emphasis> interface and plays an important role + in the event delivery model explained in the previous section. That interface gives full control over the + delivery of the event to ascendant nodes in the hierarchy, even more it gives the possibility to replace + the current event being delivered by a new event that will be transformed into the corresponding portal + behavior. However there are no guarantees that the portal will turn the returned event into a portal + behavior, here the portal provides a best effort policy, indeed sometime it is not possible to achieve + the substitution of one event by another.</para> + <para>Here the simplest implementation of a listener that does nothing except than correctly passing + the control to a parent event listener if there is one.</para> + <programlisting><![CDATA[ +public PortalNodeEvent onEvent(PortalNodeEventContext context, PortalNodeEvent event) +{ + return context.dispatch(); +} +]]></programlisting> + <para>The method <emphasis>PortalNode getNode()</emphasis> returns the current node being selected + during the event bubbler dispatching mechanism.</para> + </section> + </section> + <section> + <title>Portal session events</title> + <para>The life cycle of the session of the portal associated with the user can also raise events. This kind of + event is not bound to a portal node since it is triggered whenever a portal session is created or destroyed</para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/portalapi/PortalSessionEvent.png"/> + </imageobject> + </mediaobject> + <para>The PortalSessionEvent class</para> + + <para>There are two different types of events: + <itemizedlist> + <listitem><para>org.jboss.portal.api.session.event.PortalSessionEvent.SESSION_CREATED, fired when a new portal session is created</para></listitem> + <listitem><para>org.jboss.portal.api.session.event.PortalSessionEvent.SESSION_DESTROYED, fired when a new portal session is destroyed</para></listitem> + </itemizedlist> + </para> + </section> + <section> + <title>Portal user events</title> + <para>The life cycle of the portal user can also raise events such as its authentication. A subclass of the wider scope UserEvent class is + provided and triggers events whenever a user signs in or out. The UserEvent object gives access to the user name of the logged-in user through + the method <emphasis>String getId()</emphasis>.</para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/portalapi/user.event.png"/> + </imageobject> + + </mediaobject> + <para>The UserEvent class and UserAuthenticationEvent sub-classes</para> + + <para>The UserAuthenticationEvent triggers two events that can be catched: + <itemizedlist> + <listitem><para>org.jboss.portal.api.session.event.UserAuthenticationEvent.SIGN_IN, fired when a portal user signs in</para></listitem> + <listitem><para>org.jboss.portal.api.session.event.UserAuthenticationEvent.SIGN_OUT, fired when a portal user signs out</para></listitem> + </itemizedlist> + </para> + <para>Based on the UserEvent class other custom user related events could be added like one that would trigger when a new user is + being registered</para> + </section> + </section> + <section> + <title>Examples</title> + <para>The events mechanism is quite powerful, in this section of the chapter we will see few simple examples to explain how + it works.</para> + <section> + <title>UserAuthenticationEvent example</title> + <para>In this example, we will create a simple counter of the number of logged-in registered users. In order to + do that we just need to keep track of Sign-in and Sign-out events.</para> + <para>First, let's write our listener. It just a class that will implement <emphasis>org.jboss.portal.api.event.PortalEventListener</emphasis> and + its unique method <emphasis>void onEvent(PortalEventContext eventContext, PortalEvent event)</emphasis>. Here is such an example: + <programlisting role="java"><![CDATA[ +package org.jboss.portal.core.portlet.test.event; + +import[...] + +public class UserCounterListener implements PortalEventListener +{ + + /** Thread-safe long */ + private final SynchronizedLong counter = new SynchronizedLong(0); + + /** Thread-safe long */ + private final SynchronizedLong counterEver = new SynchronizedLong(0); + + public void onEvent(PortalEventContext eventContext, PortalEvent event) + { + if (event instanceof UserAuthenticationEvent) + { + UserAuthenticationEvent userEvent = (UserAuthenticationEvent)event; + if (userEvent.getType() == UserAuthenticationEvent.SIGN_IN) + { + counter.increment(); + counterEver.increment(); + } + else if (userEvent.getType() == UserAuthenticationEvent.SIGN_OUT) + { + counter.decrement(); + } + System.out.println("Counter : " + counter.get()); + System.out.println("Counter ever: " + counterEver.get()); + } + } +} + ]]></programlisting> + On this method we simply filter down to UserAuthenticationEvent then depending on the type of authentication event we update the + counters. <emphasis>counter</emphasis> keeps track of the registered and logged-in users, while counterEver only counts the number of + times people logged-in the portal.</para> + <para>Now that the Java class has been written we need to register it so that it can be called when the events are triggered. To do + so we need to register it as an MBean. It can be done by editing the sar descriptor file: + <emphasis>YourService.sar/META-INF/jboss-service.xml</emphasis> so that it looks like the following: + <programlisting><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<server> + <mbean + code="org.jboss.portal.core.event.PortalEventListenerServiceImpl" + name="portal:service=ListenerService,type=counter_listener" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <depends + optional-attribute-name="Registry" + proxy-type="attribute">portal:service=ListenerRegistry</depends> + <attribute name="RegistryId">counter_listener</attribute> + <attribute name="ListenerClassName"> + org.jboss.portal.core.portlet.test.event.UserCounterListener + </attribute> + </mbean> +</server> + ]]></programlisting> + This snippet can be kept as it is, providing you change the values: + <itemizedlist> + <listitem> + <para><emphasis role="bold">name:</emphasis> Must follow the pattern: portal:service=ListenerService,type={{UNIQUENAME}}</para> + </listitem> + <listitem> + <para><emphasis role="bold">RegistryId:</emphasis> Must match the type (here: counter_listener)</para> + </listitem> + <listitem> + <para><emphasis role="bold">ListenerClassName:</emphasis> Full path to the listener + (here: org.jboss.portal.core.portlet.test.event.UserCounterListener).</para> + </listitem> + </itemizedlist> + </para> + <para>That's it - we now have a user counter that will display it states each time a user logs-in our logs-out.</para> + </section> + <section> + <title>Achieving Inter Portlet Communication with the events mechanism</title> + <para>The first version of the Portlet Specification (JSR 168), regretfully, did not cover interaction between + portlets. The side-effect of diverting the issue to the subsequent release of the specification, has + forced portal vendors to each craft their own proprietary API to achieve inter portlet communication. Here we will + see how we can use the event mechanism to pass parameters from one portlet to the other (and only to the other portlet).</para> + <para>The overall scenario will be that Portlet B will need to be updated based on some parameter set on Portlet A. + To achieve that we will use a portal node event.</para> + <para>Portlet A is a simple Generic portlet that has a form that sends a color name: + <programlisting><![CDATA[ +public class PortletA extends GenericPortlet +{ + protected void doView(RenderRequest request, RenderResponse response) + throws PortletException, PortletSecurityException, IOException + { + response.setContentType("text/html"); + PrintWriter writer = response.getWriter(); + writer.println("<form action=\"" + response.createActionURL() + "\" method=\"post\">"); + writer.println("<select name=\"color\">"); + writer.println("<option>blue</option>"); + writer.println("<option>red</option>"); + writer.println("<option>black</option>"); + writer.println("</select>"); + writer.println("<input type=\"submit\"/>"); + writer.println("</form>"); + writer.close(); + } +} + ]]></programlisting> + </para> + <para>The other portlet (Portlet B) that will receive parameters from Portlet A is also a simple Generic portlet: + <programlisting><![CDATA[ +public class PortletB extends GenericPortlet +{ + + public void processAction(ActionRequest request, ActionResponse response) + throws PortletException, PortletSecurityException, IOException + { + String color = request.getParameter("color"); + if (color != null) + { + response.setRenderParameter("color", color); + } + } + + protected void doView(RenderRequest request, RenderResponse response) + throws PortletException, PortletSecurityException, IOException + { + String color = request.getParameter("color"); + response.setContentType("text/html"); + PrintWriter writer = response.getWriter(); + writer.println("<div" + + (color == null ? "" : " style=\"color:" + color + ";\"") + + ">some text in color</div>"); + writer.close(); + } + + // Inner listener explained after +} + ]]></programlisting> + </para> + <para>With those two portlets in hands, we just want to pass parameters from Portlet A to Portlet B (the color in + as a request parameter in our case). In order to achieve this goal, we will write an inner Listener in Portlet B + that will be triggered on any WindowActionEvent of Portlet A. This listener will create a new WindowActionEvent + on the window of Portlet B. + <programlisting role="java"><![CDATA[ +public static class Listener implements PortalNodeEventListener +{ + public PortalNodeEvent onEvent(PortalNodeEventContext context, PortalNodeEvent event) + { + PortalNode node = event.getNode(); + // Get node name + String nodeName = node.getName(); + // See if we need to create a new event or not + WindowActionEvent newEvent = null; + if (nodeName.equals("PortletAWindow") && event instanceof WindowActionEvent) + { + // Find window B + WindowActionEvent wae = (WindowActionEvent)event; + PortalNode windowB = node.resolve("../PortletBWindow"); + if (windowB != null) + { + // We can redirect + newEvent = new WindowActionEvent(windowB); + newEvent.setParameters(wae.getParameters()); + + newEvent.setMode(wae.getMode()); + newEvent.setWindowState(WindowState.MAXIMIZED); + + // Redirect to the new event + return newEvent; + } + } + // Otherwise bubble up + return context.dispatch(); + } +} + ]]></programlisting> + </para> + <para> + It is important to note here some of the important items in this listener class. + Logic used to determine if the requesting node was Portlet A.: + <programlisting>nodeName.equals("PortletAWindow")</programlisting> + </para> + <para> + Get the current window object so we can dispatch the event to it: + <programlisting>PortalNode windowB = node.resolve("../PortletBWindow");</programlisting> + </para> + <para> + Set the original parameter from Portlet A, so Portlet B can access them in its processAction(): + <programlisting>newEvent.setParameters(wae.getParameters());</programlisting> + </para> + <!-- + <para> + Modify Portlet B windowmode and/or windowstate (ie, Maximize and place in Edit Mode): + <programlisting> +newEvent.setMode(wae.getMode()); // Mode.EDIT; +newEvent.setWindowState(wae.getWindowState()); // WindowState.MAXIMIZED</programlisting> + </para> + --> + <para> + We still need to register our listener as an mbean: + <programlisting role="xml"> +<![CDATA[<mbean + code="org.jboss.portal.core.event.PortalEventListenerServiceImpl" + name="portal:service=ListenerService,type=test_listener" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <depends + optional-attribute-name="Registry" + proxy-type="attribute">portal:service=ListenerRegistry</depends> + <attribute name="RegistryId">test_listener</attribute> + <attribute name="ListenerClassName"> + org.jboss.portal.core.samples.basic.event.PortletB$Listener + </attribute> +</mbean>]]></programlisting> + For node events, we also need to declare on which node we want to listen, this is done by modifying + the <literal>*-object.xml</literal> that defines your portal nodes. In this example we want to trigger + the listener each time the window containing the portlet A is actioned. We can add the <literal>listener</literal> + tag to specify that out listener with <literal>RegistryId</literal>=test_listener should be triggered + on events on the embedding object. + <programlisting> +<![CDATA[... + <window> + <window-name>PortletAWindow</window-name> + <instance-ref>PortletAInstance</instance-ref> + <region>center</region> + <height>0</height> + <listener>test_listener</listener> + </window> +...]]> + </programlisting> + Of course we could have added it at the page level instead of the window level. Note that a unique listener + can be specified, the event mechanism is primarily done to let the developer change the navigation state of the + portal, this example being a nice side-effect of this feature. + </para> + <note><para>The portlet 2.0 specification (JSR 286) will cover Inter Portlet Communication so that portlets using it + can work with different portal vendors.</para></note> + </section> + <section> + <title>Link to other pages</title> + <para>Linking to some other pages or portals is also out of the scope of the portlet + specification. As seen previously JBoss Portal offers an API in order to create links + to other portal nodes. The JBoss request gives access to the current window node from + which we can navigate from.</para> + <programlisting role="java"> +<![CDATA[ +// Get the ParentNode. Since we are inside a Window, the Parent is the Page +PortalNode thisNode = req.getPortalNode().getParent(); + +// Get the Node in the Portal hierarchy tree known as "../default" +PortalNode linkToNode = thisNode.resolve("../default"); + +// Create a RenderURL to the "../default" Page Node +PortalNodeURL pageURL = resp.createRenderURL(linkToNode); + +// Output the Node's name and URL for users +html.append("Page: " + linkToNode.getName() + " -> "); +html.append("<a href=\"" + pageURL.toString() + "\">" + linkToNode.getName() + "</a>"); + ]]></programlisting> + <para>From this, it is easy to create a menu or sitemap, the <emphasis>List getChildren()</emphasis> + method will return all the child nodes on which the user has the view right access.</para> + </section> + <section> + <title>Samples</title> + <para>Those examples are available in the core-samples package in the sources of JBoss Portal. + There are more examples of events usage in the samples delivered with JBoss Portal. One of them + shows the usage of a portal node event to only have one window in normal mode at a time in a region. + Anytime another window is being put in normal mode, all the other windows of the same regions + are automatically minimized.</para> + </section> + </section> +</chapter> + <chapter id="clustering"> + <!--<chapterinfo> + <author> + <firstname>Julien</firstname> + <surname>Viet</surname> + </author> + <author> + <firstname>Roy</firstname> + <surname>Russo</surname> + </author> + </chapterinfo>--> + <title>Clustering Configuration</title> + <para>This section covers configuring JBoss Portal for a clustered environment.</para> + <section> + <title>Introduction</title> + <para>JBoss Portal leverages various clustered services that are found in JBoss Application Server. This section briefly details how each is leveraged: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">JBoss Cache:</emphasis> + Used to replicate data among the different hibernate session factories that are deployed in + each node of the cluster. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">JBoss HA Singleton:</emphasis> + <orderedlist> + <listitem><para>Used to make the deployer a singleton on the cluster, in order to avoid + concurrency issues when + deploying the various *-object.xml files. Without that, each node would try to create the + same objects in the database when it deploys an archive containing such descriptors.</para></listitem> + <listitem><para>Used with JCR. The Apache Jackrabbit server is not able to run in a cluster + by itself, therefore we make a singleton on the cluster. This provides HA-CMS, which is + similar to the current HA JBossMQ provided in JBoss AS.</para></listitem> + </orderedlist> + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">HA-JNDI:</emphasis> + Used to replicate a proxy that will talk to the HA CMS on the cluster. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Http Session Replication:</emphasis> + Used to replicate the portal and the portlet sessions. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">JBoss SSO:</emphasis> + Used to replicate the user identity, an authenticated user does not have to login again when failover occurs. + </para> + </listitem> + </itemizedlist> + + <note><title>Note</title><para>JBoss Clustering details can be found in the + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossHA">Wiki&... + or the + <ulink url="http://labs.jboss.com/jbossas/docs/">clustering documentation</ulink>.</para> + </note> + <mediaobject> + <imageobject> + <imagedata fileref="images/clustering/overview.png" scalefit="1"/> + </imageobject></mediaobject> + </section> + <section> + <title>Considerations</title> + <para>When you want to run JBoss Portal on a cluster there are a few things to keep in mind: + <itemizedlist> + <listitem><para>Deploy the portal under the <emphasis role="bold">all</emphasis> application server configuration as it contains the clustering services that is leveraged by JBoss Portal.</para></listitem> + <listitem><para>All the portal instances have to use the same datasource : the database is used to store the portal + persistent state like pages. If you don't use a shared database then you will have consistency problems.</para></listitem> + </itemizedlist></para> + </section> + + <section> + <title>JBoss Portal Clustered Services</title> + + <section id="PortalSessionReplication"> + <title>Portal Session Replication</title> + <para>The portal associates with each user a http session in order to keep specific objects such as: + <itemizedlist> + <listitem><para>Navigational state : this is mainly the state of different portlet windows that the user will manipulate + during its interactions with the portal. For instance a maximized portlet window with specific render parameters.</para></listitem> + <listitem><para>WSRP objects : the WSRP protocol can require to provide specific cookies during interactions with a remote + portlet.</para></listitem> + </itemizedlist> + Replicating the portal session ensures that this state will be kept in sync on the cluster, e.g The user will see exactly + the same portlet window on every node of the cluster. The activation of the portal session replication is made through the + configuration of the web application that is the main entry point of the portal. This setting is available in the file + <emphasis>jboss-portal.sar/portal-server.war/WEB-INF/web.xml</emphasis></para> + <para> + <programlisting><![CDATA[ +<web-app> + <description>JBoss Portal</description> + <!-- Comment/Uncomment to enable portal session replication --> + <distributable/> + ... +</web-app> +]]></programlisting> + </para> + </section> + + <section> + <title>Hibernate clustering</title> + <para>JBoss Portal leverages hibernate for its database access. In order to improve performances it uses + the caching features provided by hibernate. On a cluster the cache needs to be replicated in order + to avoid state inconsistencies. Hibernate is configured with JBoss Cache which performs that synchronization transparently. + Therefore the different hibernate services must be configured to use JBoss Cache. The following hibernate configurations + needs to use a replicated JBoss Cache : + <itemizedlist> + <listitem><para><emphasis>jboss-portal.sar/conf/hibernate/user/hibernate.cfg.xml</emphasis></para></listitem> + <listitem><para><emphasis>jboss-portal.sar/conf/hibernate/instances/hibernate.cfg.xml</emphasis></para></listitem> + <listitem><para><emphasis>jboss-portal.sar/conf/hibernate/portal/hibernate.cfg.xml</emphasis></para></listitem> + <listitem><para><emphasis>jboss-portal.sar/conf/hibernate/portlet/hibernate.cfg.xml</emphasis></para></listitem> + </itemizedlist> + The cache configuration should look like : + <programlisting><![CDATA[ +<!-- + | Uncomment in clustered mode : use transactional replicated cache + --> + <property name="cache.provider_class">org.jboss.portal.core.hibernate.JMXTreeCacheProvider + </property> + <property name="cache.object_name">portal:service=TreeCacheProvider,type=hibernate + </property> + +<!-- + | Comment in clustered mode + <property name="cache.provider_configuration_file_resource_path"> + conf/hibernate/instance/ehcache.xml</property> + <property name="cache.provider_class">org.hibernate.cache.EhCacheProvider</property> +--> +]]></programlisting> + Also we need to ensure that the cache is deployed by having in the file <emphasis>jboss-portal.sar/META-INF/jboss-service.xml</emphasis> + the cache service uncommented : + <programlisting><![CDATA[ +<!-- + | Uncomment in clustered mode : replicated cache for hibernate + --> + <mbean + code="org.jboss.cache.TreeCache" + name="portal:service=TreeCache,type=hibernate"> + <depends>jboss:service=Naming</depends> + <depends>jboss:service=TransactionManager</depends> + <attribute name="TransactionManagerLookupClass"> + org.jboss.cache.JBossTransactionManagerLookup</attribute> + <attribute name="IsolationLevel">REPEATABLE_READ</attribute> + <attribute name="CacheMode">REPL_SYNC</attribute> + <attribute name="ClusterName">portal.hibernate</attribute> + </mbean> + + <mbean + code="org.jboss.portal.core.hibernate.JBossTreeCacheProvider" + name="portal:service=TreeCacheProvider,type=hibernate"> + <depends optional-attribute-name="CacheName">portal:service=TreeCache,type=hibernate + </depends> + </mbean> +]]></programlisting> + More information can be found <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossCacheHibernate&qu...;. + </para> + </section> + + <section> + <title>Identity clustering</title> + <para>JBoss Portal leverages the servlet container authentication for its own authentication mechanism. When + the user is authenticated on one particular node he will have to reauthenticate again if a different + node of the cluster (during a failover for instance) is used. This is valid only for the <emphasis>FORM</emphasis> + based authentication which is the default form of authentication that JBoss Portal uses. Fortunately JBoss + provides transparent reauthentication of the user called JBoss clustered SSO. Its configuration can be found + in <literal>$JBOSS_HOME/server/all/deploy/jboss-web.deployer/server.xml</literal> and you will need to + uncomment the following valve: + <programlisting><![CDATA[<Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" />]]></programlisting> + + More information can be found <ulink url="http://www.jboss.org/wiki/Wiki.jsp?page=SingleSignOn">h...;. + </para> + </section> + + <section> + <title>CMS clustering</title> + <para>The CMS backend storage relies on the Apache Jackrabbit project. Jackrabbit does not support clustering out of the box. + So the portal run the Jackrabbit service on one node of the cluster using the + <ulink url="http://www.onjava.com/pub/a/onjava/2003/08/20/jboss_clustering.... technology. + The file <emphasis>jboss-portal.sar/portal-cms.sar/META-INF/jboss-service.xml</emphasis> contains the configuration. We will + not reproduce it in this documentation as the changes are quite complex and numerous. Access from all nodes of the cluster + is provided by a proxy bound in HA-JNDI. In order to avoid any bottleneck JBoss Cache is leveraged to cache CMS content cluster + wide.</para> + <mediaobject> + <imageobject> + <imagedata fileref="images/clustering/cms.png"/> + </imageobject></mediaobject> + </section> + + </section> + + <section> + <title>Setup</title> + <para>We are going to outline how to setup a two node cluster on the same machine in order to test JBoss Portal HA. The only + missing part from the full fledged setup is the addition of a load balancer in front of Apache Tomcat. However a lot of documentation + exist on the subject. A detailed step by step setup of Apache and mod_jk is available from the + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=UsingMod_jk1.2WithJBos... Wiki</ulink>.</para> + <para>As we need two application servers running at the same time, we must avoid any conflict. For instance we will + need Apache Tomcat to bind its socket on two different ports otherwise a network conflict will occur. We will leverage + the service binding manager <ulink url="http://docs.jboss.org/jbossas/jboss4guide/r3/html/ch10.html&quo... chapter</ulink> of + the JBoss AS documentation.</para> + <para>The first step is to copy the <emphasis>all</emphasis> configuration of JBoss into two separate + configurations that we name <emphasis>ports-01</emphasis> and <emphasis>ports-02</emphasis> : + <programlisting><![CDATA[ +>cd $JBOSS_HOME/server +>cp -r all ports-01 +>cp -r all ports-02 +]]></programlisting> + </para> + <para>Edit the file <emphasis>$JBOSS_HOME/server/ports-01/conf/jboss-service.xml</emphasis> and uncomment + the service binding manager : + <programlisting><![CDATA[ +<mbean code="org.jboss.services.binding.ServiceBindingManager" + name="jboss.system:service=ServiceBindingManager"> + <attribute name="ServerName">ports-01</attribute> + <attribute name="StoreURL"> + ${jboss.home.url}/docs/examples/binding-manager/sample-bindings.xml</attribute> + <attribute name="StoreFactoryClassName">org.jboss.services.binding.XMLServicesStoreFactory</attribute> +</mbean> +]]></programlisting> + </para> + <para>Edit the file <emphasis>$JBOSS_HOME/server/ports-02/conf/jboss-service.xml</emphasis>, uncomment + the service binding manager and change the value <emphasis>ports-01</emphasis> into <emphasis>ports-02</emphasis>: + <programlisting><![CDATA[ +<mbean code="org.jboss.services.binding.ServiceBindingManager" + name="jboss.system:service=ServiceBindingManager"> + <attribute name="ServerName">ports-02</attribute> + <attribute name="StoreURL"> + ${jboss.home.url}/docs/examples/binding-manager/sample-bindings.xml</attribute> + <attribute name="StoreFactoryClassName"> + org.jboss.services.binding.XMLServicesStoreFactory</attribute> +</mbean>]]></programlisting> + </para> + <para>Setup a database that will be shared by the two nodes and obviously we cannot use + an embedded database. For instance using postgresql we would need to copy the file <emphasis>portal-postgresql-ds.xml</emphasis> + into <emphasis>$JBOSS_HOME/server/ports-01/deploy</emphasis> and <emphasis>$JBOSS_HOME/server/ports-02/deploy</emphasis>. + </para> + <para>Copy JBoss Portal HA to the deploy directory of the two configurations.</para> + + <!-- adding instruction about jboss cache versioning --> + <formalpara> + <title>JBoss Cache</title> + <para> + To improve CMS performance JBoss Cache is leveraged to cache the content cluster wide. + We recommend that you use the following version of JBoss Cache for best performance: + </para> +</formalpara> + <itemizedlist> + <listitem><para> + <emphasis>JBoss Cache 1.4.0.SP1 and above</emphasis></para> + </listitem> + <listitem><para> + <emphasis>JGroups 2.2.7 or 2.2.8</emphasis></para> + </listitem> + </itemizedlist> + <para> + When building from source the following command: + <literal>{core}/build.xml deploy-ha</literal> automatically upgrades your JBoss Cache version. + </para> + <para> + <emphasis>Alternative:</emphasis> + If upgrading your JBoss Cache version is not an option, the following configuration + change is needed in the + <literal>jboss-portal-ha.sar/portal-cms.sar/META-INF/jboss-service.xml</literal>. + Replace the following configuration in the + <emphasis>cms.pm.cache:service=TreeCache</emphasis> + Mbean: + </para> + <programlisting role="XML"><![CDATA[ +<!-- + Configuring the PortalCMSCacheLoader + CacheLoader configuration for 1.4.0 +--> +<attribute name="CacheLoaderConfiguration"> + <config> + <passivation>false</passivation> + <preload></preload> + <shared>false</shared> + <cacheloader> + <class>org.jboss.portal.cms.hibernate.state.PortalCMSCacheLoader</class> + <properties></properties> + <async>false</async> + <fetchPersistentState>false</fetchPersistentState> + <ignoreModifications>false</ignoreModifications> + </cacheloader> + </config> +</attribute>]]> + </programlisting> + <para> + with the following configuration: + </para> + <programlisting role="XML"><![CDATA[ +<!-- + Configuring the PortalCMSCacheLoader + CacheLoader configuratoon for 1.2.4SP2 +--> +<attribute name="CacheLoaderClass">org.jboss.portal.cms.hibernate.state.PortalCMSCacheLoader +</attribute> +<attribute name="CacheLoaderConfig" replace="false"></attribute> +<attribute name="CacheLoaderPassivation">false</attribute> +<attribute name="CacheLoaderPreload"></attribute> +<attribute name="CacheLoaderShared">false</attribute> +<attribute name="CacheLoaderFetchTransientState">false</attribute> +<attribute name="CacheLoaderFetchPersistentState">false</attribute> +<attribute name="CacheLoaderAsynchronous">false</attribute>]]></programlisting> + +<para>Finally we can start both servers, open two shells and execute : + <programlisting><![CDATA[ +>cd $JBOSS_HOME/bin +>sh run.sh -c ports-01 +]]></programlisting> + <programlisting><![CDATA[ +>cd $JBOSS_HOME/bin +>sh run.sh -c ports-02 +]]></programlisting> + </para> + </section> + + <section id="portlet_session_replication"> + <title>Portlet Session Replication</title> + <para>Web containers offer the capability to replicate sessions of web applications. In the context of a portal using portlets the use case is different. The portal itself is a web application + that benefits of web application session replication. We have to make the distinction between local or remote portlets : + <itemizedlist> + <listitem><para>Local portlets are web applications deployed in the same virtual machine as the portal + web application. At runtime the access to a portlet is done using the mechanism of request dispatching. The portlet + session is actually a mere wrapper of the underlying http session of the web application in which the portlet + is deployed.</para></listitem> +<listitem><para>Remote portlets are accessed using a web service, we will not cover the replication in this chapter.</para></listitem> + </itemizedlist></para> + <para>The servlet specification is very loose on the subject of replication and does not state anything about + the replication of sessions during a dispatched request. JBoss Portal offers a portlet session replication + mechanism that leverages the usage of the portal session instead which has several advantages + </para> + <itemizedlist> + <listitem><para>Replicate only the portlet that requires it.</para></listitem> + <listitem><para>Portal session replication is just web application replication and is very standard.</para></listitem> + </itemizedlist> + <para>There are, however, some limitations. For example, you can only replicate portlet-scoped attributes of a portlet + session. This means that any application-scoped attribute are not replicated.</para> + <section> + <title>JBoss Portal configuration</title> + <para>The mandatory step to make JBoss Portal able to replicate portlet sessions is to configure + the portal web application to be distributed as explained in <xref linkend="PortalSessionReplication"/></para> + </section> + <section> + <title>Portlet configuration</title> + <para>In order to activate portlet session replication you need to:</para> + <itemizedlist> + <listitem><para>Add a Portal-specific listener class to the <literal>/WEB-INF/web.xml</literal> file of your portlet web application</para></listitem> + <listitem><para>Configure your portlet to be distributed in the <literal>/WEB-INF/jboss-portlet.xml</literal> file</para></listitem> + </itemizedlist> + + <programlisting><![CDATA[ +<web-app> + ... + <listener> + <listener-class> org.jboss.portal.portlet.session.SessionListener </listener-class> + </listener> + ... +</web-app> +]]></programlisting> + + <para>Example web.xml</para> + +<programlisting><![CDATA[ +<portlet-app> + ... + <portlet> + <portlet-name>YourPortlet</portlet-name> + ... + <session-config> + <distributed>true</distributed> + </session-config> + ... + </portlet> + ... +</portlet-app> +]]></programlisting> + + <para>Configure YourPortlet to be replicated in jboss-portlet.xml</para> + + </section> + <section> + <title>Limitations</title> + <para>As we noted above there are advantages as well as limitations to the clustering configuration</para> + <itemizedlist> + <listitem><para>You can only replicate portlet scoped attributes of a portlet. The main reason of this + is to keep consistency with the session state. If accessing a portlet would trigger replication + of application scoped attribute during the rendering of a page then another portlet on the same + page could use this attribute for generating its markup. Then the state seen by this second portlet + would not necessarily be the same depending on the order in which the portlets on this page are rendered.</para></listitem> +<listitem><para>Mutable objects need an explicit call to <emphasis>setAttribute(String name, Object value)</emphasis> + on the portlet session object in order to trigger replication by the container.</para></listitem> + </itemizedlist> + <para> + <programlisting><![CDATA[ +public void processAction(ActionRequest req, ActionResponse resp) + throws PortletException, IOException +{ + ... + if ("addItem".equals(action)) + { + PortletSession session = req.getPortletSession(); + ShoppingCart cart = (PortletSession)session.getAttribute("cart"); + cart.addItem(item); + + // Perform an explicit set in order to signal to the container that the object + // state has changed + session.setAttribute("cart", cart); + } + ... +} +]]></programlisting> + </para> + </section> + </section> +</chapter> + <chapter id="wsrp"> +<!-- <chapterinfo> + <author> + <firstname>Julien</firstname> + <surname>Viet</surname> + </author> + <author> + <firstname>Chris</firstname> + <surname>Laprun</surname> + </author> + </chapterinfo>--> + + <title>Web Services for Remote Portlets (WSRP)</title> + + <section> + <title>Introduction</title> + <para>The Web Services for Remote Portlets specification defines a web service interface for accessing and + interacting with interactive presentation-oriented web services. It has been produced through the efforts of + the Web Services for Remote Portlets (WSRP) OASIS Technical Committee. It is based on the requirements + gathered and on the concrete proposals made to the committee. + </para> + + <para>Scenarios that motivate WSRP functionality include: + <itemizedlist> + <listitem><para>Content hosts, such as portal servers, providing Portlets as presentation-oriented web services + that can be used by aggregation engines.</para> + </listitem> + <listitem><para>Aggregating frameworks, including portal servers, consuming presentation-oriented web services + offered by content providers and integrating them into the framework.</para> + </listitem> + </itemizedlist> + </para> + + <para>More information on WSRP can be found on the + <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp... website for WSRP</ulink>. + We suggest reading the <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp... + </ulink> for a good, albeit technical, overview of WSRP. + </para> + </section> + + <section id="wsrp_support"> + <title>Level of support in JBoss Portal</title> + <para>The WSRP Technical Committee defined + <ulink url="http://www.oasis-open.org/committees/download.php/3073">... Use Profiles</ulink> + to help with WSRP interoperability. We will refer to terms defined in that document in + this section. + </para> + + <para>JBoss Portal provides a Simple level of support for our WSRP Producer except that out-of-band registration + is not currently handled. We support in-band registration and persistent local state (which are + defined at the Complex level). + </para> + + <para>On the Consumer side, JBoss Portal provides a Medium level of support for WSRP, except that we only handle + HTML markup (as Portal itself doesn't handle other markup types). We do support explicit portlet cloning and + we fully support the PortletManagement interface. + </para> + + <para>As far as caching goes, we have Level 1 Producer and Consumer. We support Cookie handling properly on the + Consumer and our Producer requires initialization of cookies (as we have found that it improved interoperabilty + with some consumers). We don't support custom window states or modes, as Portal doesn't either. We do, however, + support CSS on both the Producer (though it's more a function of the portlets than inherent Producer + capability) and Consumer. + </para> + + <para>While we provide a complete implementation of WSRP 1.0, we do need to go through the + <ulink url="http://www.oasis-open.org/committees/download.php/6018">... statements</ulink> + and perform more interoperability testing (an area that needs to be better supported by the WSRP Technical + Committee and Community at large). + </para> + </section> + + <section> + <title>Deploying JBoss Portal's WSRP services</title> + <para> + JBoss Portal provides a complete support of WSRP 1.0 standard interfaces and offers both consumer and producer + services. WSRP support is provided by the <filename>portal-wsrp.sar</filename> service archive, included in + the main <filename>jboss-portal.sar</filename> service archive, if you've obtained JBoss Portal from a binary + distribution. If you don't intend on using WSRP, we recommend that you remove <filename>portal-wspr.sar</filename> + from the main <filename>jboss-portal.sar</filename> service archive. + </para> + <para>If you've obtained the source distribution of JBoss Portal, you need to build and deploy the WSRP service + separately. Please follow the instructions on how to install + <ulink url="http://docs.jboss.com/jbportal/v2.6/reference-guide/en/html/ins... + Portal from the sources</ulink>. Once this is done, navigate to + <filename>JBOSS_PORTAL_HOME_DIRECTORY/wsrp</filename> and type: <command>build deploy</command> + At the end of the build process, <filename>portal-wsrp.sar</filename> is copied to + <filename>JBOSS_HOME/server/default/deploy</filename>. + </para> + + <section id="wsrp-ports"> + <title>Considerations to use WSRP when running Portal on a non-default port or hostname</title> + <para>If you have modified the port number on which Portal runs or bound your Application Server to a specific + host name, you will also need + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=WSRPChangePorts"&... the port and/or hostname + information for WSRP</ulink> as found on + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossPortal">J... Portal's wiki</ulink>. + </para> + </section> + + <section> + <title>Considerations to use WSRP with SSL</title> + <para>It is possible to use WSRP over SSL for secure exchange of data. Please refer to the + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=WSRPUseSSL">in... + on how to do so from + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossPortal">J... Portal's wiki</ulink>. + </para> + </section> + </section> + + <section> + <title>Making a portlet remotable</title> + <para>JBoss Portal does <emphasis role="bold">NOT</emphasis>, by default, expose local portlets for consumption by + remote WSRP consumers. In order to make a portlet remotely available, it must be made "remotable" by adding a + <literal>remotable</literal> element to the <filename>jboss-portlet.xml</filename> deployment descriptor for + that portlet. If a <filename>jboss-portlet.xml</filename> file does not exist, one must be added to the + <filename>WEB-INF</filename> folder of the web application containing the portlet. + </para> + <para>In the following example, the "BasicPortlet" portlet is specified as being remotable. The + <literal>remotable</literal> element is optional. + </para> + + <programlisting><![CDATA[ +<?xml version="1.0" standalone="yes"?> +<!DOCTYPE portlet-app PUBLIC "-//JBoss Portal//DTD JBoss Portlet 2.6//EN" + "http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd"> +<portlet-app> + <portlet> + <portlet-name>BasicPortlet</portlet-name> + <remotable>true</remotable> + </portlet> +</portlet-app>]]></programlisting> + + <para> + It is also possible to specify that all the portlets declared within a given <filename>jboss-portlet.xml</filename> + file have a specific "remotable" status by default. This is done by adding a single <literal>remotable</literal> + element to the root <literal>portlet-app</literal> element. Usually, this feature will be used to remotely expose + several portlets without having to specify the status for all the declared portlets. Let's look at an example: + </para> + + <programlisting><![CDATA[ +<?xml version="1.0" standalone="yes"?> +<!DOCTYPE portlet-app PUBLIC + "-//JBoss Portal//DTD JBoss Portlet 2.6//EN" + "http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd"> +<portlet-app> + <remotable>true</remotable> + <portlet> + <portlet-name>RemotelyExposedPortlet</portlet-name> + ... + </portlet> + <portlet> + <portlet-name>NotRemotelyExposedPortlet</portlet-name> + <remotable>false</remotable> + ... + </portlet> +</portlet-app>]]> + </programlisting> + + + <para> + In the example above, we defined two portlets with a default "remotable" status set to true. This means that + all portlets defined in this descriptor are, by default, exposed remotely by JBoss Portal's WSRP producer. + Note, however, that it is possible to override the default behavior by adding a <literal>remotable</literal> + element to a portlet description. In that case, the "remotable" status defined by the portlet takes precedence + over the default. In the example above, the <literal>RemotelyExposedPortlet</literal> inherits the "remotable" + status defined by default since it does not specify a <literal>remotable</literal> element in its description. + The <literal>NotRemotelyExposedPortlet</literal>, however, overrides the default behavior and is not remotely + exposed. Note that in the absence of a top-level <literal>remotable</literal> element, portlets are NOT + remotely exposed. + </para> + </section> + + <section> + <title>Consuming JBoss Portal's WSRP portlets from a remote Consumer</title> + <para>WSRP Consumers vary a lot as far as how they are configured. Most of them require that you either specify + the URL for the Producer's WSDL definition or the URLs for the individual endpoints. Please refer to your + Consumer's documentation for specific instructions. For instructions on how to do so in JBoss Portal, please + refer to <xref linkend="consumer_configuration"/>. + </para> + <para> + JBoss Portal's Producer is automatically set up when you deploy a portal instance with the WSRP service. + You can access the WSDL file at + <filename>http://{hostname}:{port}/portal-wsrp/MarkupService?wsdl</filename>. You can access the endpoint URLs + at: + <itemizedlist> + <listitem><para> + <filename>http://{hostname}:{port}/portal-wsrp/ServiceDescriptionService</filename></para> + </listitem> + <listitem><para> + <filename>http://{hostname}:{port}/portal-wsrp/MarkupService</filename></para> + </listitem> + <listitem><para> + <filename>http://{hostname}:{port}/portal-wsrp/RegistrationService</filename></para> + </listitem> + <listitem> + <para><filename>http://{hostname}:{port}/portal-wsrp/PortletManagementService</filename></para> + </listitem> + </itemizedlist> + The default hostname is <literal>localhost</literal> and the default port is 8080. + </para> + </section> + + <section id="consumer_configuration"> + <title>Consuming remote WSRP portlets in JBoss Portal</title> + <section> + <title>Overview</title> + <para> + To be able to consume WSRP portlets exposed by a remote producer, JBoss Portal's WSRP consumer needs to know + how to access that remote producer. One can configure access to a remote producer using WSRP Producer + descriptors. Alternatively, a portlet is provided to configure remote producers. + </para> + <para> + Once a remote producer has been configured, it can be made available + in the list of portlet providers in the Management portlet on the Admin page of JBoss Portal. You can then + examine the list of portlets that are exposed by this producer and configure the portlets just like you + would for local portlets. + </para> + <para> + JBoss Portal's default configuration exposes some of the sample portlets for remote consumption. As a way to + test the WSRP service, a default consumer has been configured to consume these portlets. To make sure that + the service indeed works, check that there is a portlet provider with the + <literal>self</literal> + identifier in the portlet providers list in the Management portlet of the Admin page. All local portlets + marked as remotable are exposed as remote portlets via the + <literal>self</literal> + portlet + provider so that you can check that they work as expected with WSRP. The + <filename>portal-wsrp.sar</filename> + file contains a WSRP Producer descriptor (<filename>default-wsrp.xml</filename>) that configures this + default producer. This file can be edited or removed if needed. + </para> + </section> + + <section> + <title>Configuring a remote producer walk-through</title> + <para> + Let's work through the steps of defining access to a remote producer so that its portlets can be + consumed within JBoss Portal. We will configure access to BEA's public WSRP producer. We will first examine + how to do so using the configuration portlet. We will then show how the same result can be accomplish with + a producer descriptor. + </para> + + <section id="consumer_gui"> + <title>Using the configuration portlet</title> + <para> + As of Portal 2.6, a configuration portlet is provided to configure access to remote WSRP Producers + grahically. You can access it at + <filename>http://{hostname}:{port}/portal/auth/portal/admin/WSRP</filename> + or by logging in as a Portal administrator and clicking on the WSRP tab in the Admin portal. If all went + well, you should see something similar to this: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/config_init.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + This screen presents all the configured producers associated with their status and possible actions on + them. A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a + portlet provider. Deactivating it will remove it from the list of available portlet providers. Note also + that a Consumer can be marked as requiring refresh meaning that the information held about it might not + be up to date and refreshing it from the remote Producer might be a good idea. This can happen for + several reasons: the service description for that remote Producer has not been fetched yet, the cached + version has expired or modifications have been made to the configuration that could potentially + invalidate it, thus requiring re-validation of the information. + </para> + + <para> + Next, we create a new Consumer which we will call<literal>bea</literal>. Type "<literal>bea</literal>" in + the + "Create a consumer named:" field then click on "Create consumer": + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/config_create.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + You should now see a form allowing you to enter/modify the information about the Consumer. + Set the cache expiration value to 300 seconds and enter the WSDL URL for the producer in the text field + and press the "Refresh &amp; Save" button: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/config_usewsdl.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + This will retrieve the service description associated with the Producer which WSRP is described by the + WSDL file found at the URL you just entered. In our case, querying the service description will allow us + to learn that the Producer requires registration and that it expects a value for the registration + property named <literal>registration/consumerRole</literal>: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/config_refresh.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + <note><title>Note</title><para>At this point, there is no automated way to learn about which possible values (if any) are + expected by the remote Producer. In the case of BEA's public producer, the possible values are + indicated in the registration property description. This is not always the case... Please refer to + the specific Producer's documentation.</para> + </note> + Enter "<literal>public</literal>" as the value for the registration property and press "Save &amp; + Refresh" once more. You should now + see something similar to: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/config_end.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + The Consumer for the <literal>bea</literal> Producer should now be available as a portlet provider and + is ready to be used. + </para> + <para> + A producer is configured, by default, by retrieving the producer's information via a WSDL URL. There are + rare cases, however, where URLs need to be provided for each of the producer's end points. You can do + exactly that by unchecking the "Use WSDL?" checkbox, as is the case for the <literal>self</literal> + producer: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/config_self.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + </section> + + <section> + <title>Using a WSRP Producer XML descriptor</title> + + <para>We will create a <filename>public-bea-wsrp.xml</filename> descriptor. Note that the actual name does not + matter as long as it ends with <filename>-wsrp.xml</filename>: + </para> + <programlisting role="XML"><![CDATA[ +<?xml version='1.0' encoding='UTF-8' ?> +<!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer Configuration 2.6//EN" + "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd"> +<deployments> + <deployment> + <wsrp-producer id="bea" expiration-cache="300"> + <endpoint-wsdl-url>http://wsrp.bea.com:7001/producer/producer?WSDL</endpoint-wsdl-url> + <registration-data> + <property> + <name>registration/consumerRole</name> + <lang>en</lang> + <value>public</value> + </property> + </registration-data> + </wsrp-producer> + </deployment> +</deployments>]]></programlisting> + <para> + This producer descriptor gives access to BEA's public WSRP producer. We will look at the details of the different elements later. Note for now the <literal>producer-id</literal> element with a "<literal>bea</literal>" value. Put this file in the deploy directory and start the server (with JBoss Portal and its WSRP service deployed). + </para> + <para> + <note><title>Note</title><para>A DTD and an XML Schema for WSRP Producer XML descriptors are available in + <filename>jboss-portal.sar/portal-wsrp.sar/dtd/jboss-wsrp-consumer_2_6.dtd</filename> and + <filename>jboss-portal.sar/portal-wsrp.sar/xsd/jboss-wsrp-consumer_2_6.xsd</filename></para> + </note> + </para> + </section> + + <section> + <title>Configuring access to a remote portlet</title> + <para> + Let's now look at the Admin page and the Management portlet. Click on the "Portlet definitions" tab at + the + top. Once this is done, look at the list of available portlet providers. If all went well, + you should see something similar to this: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/portlets.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + <para> + We have 3 available portlet providers: + <literal>local, self</literal> + and<literal>bea</literal>. The + <literal>local</literal> + portlet provider exposes all the portlets deployed in this particular instance of Portal. As + explained above, the + <literal>self</literal> + provider refers to the default WSRP consumer bundled with Portal that consumes + the portlets exposed by the default WSRP producer. The + <literal>bea</literal> + provider corresponds to BEA's public producer + we just configured. Select it and click on "View portlets". You should now see something similar to: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/bea.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + <para> + From there on out, you should be able to configure WSRP portlets just as any other. In particular, you + can create an instance of one of the remote portlets offered by BEA's public producer just like you would + create an instance of a local portlet and then assign it to a window in a page. If you go to that page, + you should see something similar to below for this portlet: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/result.png" align="center" valign="middle"/> + </imageobject> + </mediaobject> + </para> + </section> + </section> + + <section> + <title>WSRP Producer descriptors</title> + + <para> + A WSRP Producer descriptor is an XML file which name ends in <filename>-wsrp.xml</filename> and + which can be dropped in the deploy directory of the JBoss application server or nested in .sar files. It is + possible to configure access to several different producers within a single descriptor or use one file per + producer, depending on your needs. An XML Schema for the WSRP Producer descriptor format can be found at + <filename>jboss-portal.sar/portal-wsrp.sar/xsd/jboss-wsrp-consumer_2_6.xsd</filename>, while a (legacy) DTD + can be found at <filename>jboss-portal.sar/portal-wsrp.sar/dtd/jboss-wsrp-consumer_2_6.dtd</filename>. + + <note><title>Note</title><para>It is important to note how WSRP Producer descriptors are processed. They are read the first time the + WSRP service starts and the associated information is then put in the Portal database. Subsequent launch + of the WSRP service will use the database-stored information for all producers which identifier is + already known to Portal. More specifically, all the descriptors are scanned for producer identifiers. + Any identifier that is already known will be bypassed and the configuration associated with this remote + producer in the database will be used. If a producer identifier is found that wasn't already in the + database, that producer information will be processed and recorded in the database. Therefore, if you + wish to delete a producer configuration, you need to delete the associated information in the database + (this can be accomplished using the configuration portlet as we saw in <xref linkend="consumer_gui"/>) + <emphasis>AND</emphasis> remove the associated information in any WSRP Producer descriptor (if such + information exists) as the producer will be re-created the next time the WSRP is launched if that + information is not removed.</para> + </note> + </para> + + <section> + <title>Required configuration information</title> + + <para>Let's now look at which information needs to be provided to configure access to a remote producer. + </para> + + <para>First, we need to provide an identifier for the producer we are configuring so that we can refer to it + afterwards. This is accomplished via the mandatory + <literal>id</literal> + attribute of the + <literal>&lt;wsrp-producer&gt;</literal> + element. + </para> + + <para>JBoss Portal also needs to learn about the remote producer's endpoints to be able to connect to the + remote web services and perform WSRP invocations. Two options are currently supported to provide this + information: + </para> + + <para> + <itemizedlist> + <listitem><para>You can provide the URLs for each of the different WSRP interfaces offered by the remote + producer via the + <literal>&lt;endpoint-config&gt;</literal> + element and its + <literal>&lt;service-description-url&gt;</literal>, + <literal>&lt;markup-url&gt;</literal>, + <literal>&lt;registration-url&gt;</literal> + and + <literal>&lt;portlet-management-url&gt;</literal> + children. These URLs are + producer-specific so you will need to refer to your producer documentation or WSDL file to + determine + the appropriate values.</para> + </listitem> + <listitem><para>Alternatively, and this is the easiest way to configure your producer, you can provide a URL + pointing to the WSDL description of the producer's WSRP services. This is accomplished via the + <literal>&lt;endpoint-wsdl-url&gt;</literal> + element. JBoss Portal will then + heuristically determine, from the information contained in the WSDL file, how to connect + appropriately + to the remote WSRP services. + <note><title>Note</title><para>It is important to note that, when using this method, JBoss Portal will try to match a port + name to an interface based solely on the provided name. There are no standard names for these + ports so it is possible (though rare) that this matching process fails. In this case, you should + look at the WSDL file and provide the endpoint URLs manually, as per the previous method.</para> + </note></para> + </listitem> + </itemizedlist> + </para> + + <para>Both the + <literal>id</literal> + attribute and either + <literal>&lt;endpoint-config&gt;</literal> + or + <literal>&lt;endpoint-wsdl-url&gt;</literal> + elements + are required for a functional remote producer configuration. + </para> + </section> + + <section> + <title>Optional configuration</title> + <para>It is also possible to provide addtional configuration, which, in some cases, might be important to + establish a proper connection to the remote producer. + </para> + + <para>One such optional configuration concerns caching. To prevent useless roundtrips between the local + consumer and the remote producer, it is possible to cache some of the information sent by the producer + (such + as the list of offered portlets) for a given duration. The rate at which the information is refreshed is + defined by the + <literal>expiration-cache</literal> + attribute of the + <literal>&lt;wsrp-producer&gt;</literal> + element which specifies the + refreshing period in seconds. For example, providing a value of 120 for expiration-cache means that the + producer information will not be refreshed for 2 minutes after it has been somehow accessed. If no value + is provided, JBoss Portal will always access the remote producer regardless of whether the remote + information has changed or not. Since, in most instances, the information provided by the producer does + not + change often, we recommend that you use this caching facility to minimize bandwidth usage. + </para> + + <para>Additionally, some producers require consumers to register with them before authorizing them to access + their offered portlets. If you know that information beforehand, you can provide the required registration + information in the producer configuration so that the Portal consumer can register with the remote + producer when required. + <note><title>Note</title><para>At this time, though, only simple String properties are supported and it is not possible to + configure complex registration data. This should however be sufficient for most cases.</para> + </note> + </para> + + <para>Registration configuration is done via the + <literal>&lt;registration-data&gt;</literal> + element. Since JBoss Portal can generate the mandatory information for you, if the remote producer does + not + require any registration properties, you only need to provide an empty + <literal>&lt;registration-data&gt;</literal> + element. Values for the registration properties + required by the remote producer can be provided via + <literal>&lt;property&gt;</literal> + elements. See the example below for more details. Additionally, you can override the default consumer + name + automatically provided by JBoss Portal via the + <literal>&lt;consumer-name&gt;</literal> + element. If you choose to provide a consumer name, please remember that this should uniquely identify + your + consumer. + </para> + </section> + </section> + + <section> + <title>Examples</title> + + <para> + Here is the configuration of the <literal>self</literal> producer as found in + <filename>default-wsrp.xml</filename> with a cache expiring every five minutes: + </para> + + + <programlisting><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer Configuration 2.6//EN" + "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd"> + +<deployments> + <deployment> + <wsrp-producer id="self" expiration-cache="300"> + <!-- + we need to use the individual endpoint configuration because the configuration via + wsdl forces an immediate attempt to access the web service description which is not + available yet at this point of deployment + --> + <endpoint-config> + <service-description-url> + http://localhost:8080/portal-wsrp/ServiceDescriptionService + </service-description-url> + <markup-url>http://localhost:8080/portal-wsrp/MarkupService</markup-url> + <registration-url> + http://localhost:8080/portal-wsrp/RegistrationService + </registration-url> + <portlet-management-url> + http://localhost:8080/portal-wsrp/PortletManagementService + </portlet-management-url> + </endpoint-config> + <registration-data/> + </wsrp-producer> + </deployment> +</deployments>]]> + </programlisting> + + + <para>Here is an example of a WSRP descriptor with a 2 minute caching time and manual definition of the + endpoint URLs: + </para> + + + <programlisting><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer Configuration 2.6//EN" + "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd"> + +<deployments> + <deployment> + <wsrp-producer id="MyProducer" expiration-cache="120"> + <endpoint-config> + <service-description-url> + http://www.someproducer.com/portal-wsrp/ServiceDescriptionService + </service-description-url> + <markup-url> + http://www.someproducer.com/portal-wsrp/MarkupService + </markup-url> + <registration-url> + http://www.someproducer.com/portal-wsrp/RegistrationService + </registration-url> + <portlet-management-url> + http://www.someproducer.com/portal-wsrp/PortletManagementService + </portlet-management-url> + </endpoint-config> + </wsrp-producer> + </deployment> +</deployments>]]></programlisting> + + + <para>Here is an example of a WSRP descriptor with endpoint definition via remote WSDL file, registration + data and cache expiring every minute: + </para> + + + <programlisting><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer Configuration 2.6//EN" + "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd"> + +<deployments> + <deployment> + <wsrp-producer id="AnotherProducer" expiration-cache="60"> + <endpoint-wsdl-url>http://example.com/producer/producer?WSDL</endpoi... + <registration-data> + <property> + <name>property name</name> + <lang>en</lang> + <value>property value</value> + </property> + </registration-data> + </wsrp-producer> + </deployment> +</deployments>]]></programlisting> + + </section> + </section> + + <section> + <title>Consumers maintenance</title> + + <section> + <title>Modifying a currently held registration</title> + + <section> + <title>Registration modification for service upgrade</title> + <para> + Producers often offer several levels of service depending on consumers' subscription levels (for + example). + This is implemented at the WSRP level with the registration concept: producers assert which level of + service to provide to consumers based on the values of given registration properties. + </para> + <para> + It is therefore sometimes necessary to modify the registration that concretizes the service agreement + between a consumer and a producer. An example of easily available producer offering different level of + services is BEA's public producer. We configured access to that producer in + <xref linkend="consumer_gui"/>. + If you recall, the producer was requiring registration and required a value to be provided for the + <literal>registration/consumerRole</literal> + property. The description of that property indicated that + three values were possible: <literal>public</literal>, <literal>partner</literal> or + <literal>insider</literal> each corresponding to a different service level. We registered using the + <literal>public</literal> service level. This gave us access to three portlets as shown here: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/bea.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + <para> + Suppose now that we would like to upgrade our service level to the "insider" level. We will need to + tell BEA's producer that our registration data has been modified. Let's see how to do this. Assuming you + have configured access to the producer as previously described, please go to the configuration screen for + the <literal>bea</literal> producer and modify the value of the <literal>registration/consumerRole</literal> + to <literal>insider</literal> instead of <literal>public</literal>: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/modify_reg_start.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + Now click on "Update properties" to save the change. A "Modify registration" button should now appear to + let you send this new data to the remote producer: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/modify_reg_modify.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + Click on this new button and, if everything went well and your updated registration has been accepted by + the remote producer, you should see something similar to: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/modify_reg_end.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + You can now check the list of available portlets from the <literal>bea</literal> provider and verify that + new portlets are now available: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/bea_insider.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + + </section> + + <section id="reg_mod_error"> + <title>Registration modification on producer error</title> + + <para> + It can also happen that a producer administrator decided to require more information from registered + consumers. In this case, invoking operations on the producer will fail with an + <literal>OperationFailedFault</literal>. JBoss Portal will attempt to help you in this + situation. Let's walk through an example using the <literal>self</literal> producer. Let's assume that + registration is required without any registration properties (as is the case by default). If you go to + the configuration screen for this producer, you should see: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/config_self.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + + Now suppose that the administrator of the producer now requires a value to be provided for an + <literal>email</literal> registration property. We will actually see how to do perform this operation + in JBoss Portal when we examine how to configure Portal's producer in <xref linkend="producer_config"/>. + Operations with this producer will now fail. If you suspect that a registration modification is required, + you should go to the configuration screen for this remote producer and refresh the information held by + the consumer by pressing "Refresh &amp; Save": + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/modify_reg_self.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + + As you can see, the configuration screen now shows the currently held registration information and + the expected information from the producer. Enter a value for the <literal>email</literal> property + and then click on "Modify registration". If all went well and the producer accepted your new registration + data, you should see something similar to: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/modify_reg_self_end.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + + <note><title>Note</title><para>As of WSRP 1, it is rather difficult to ascertain for sure what caused an + <literal>OperationFailedFault</literal> as it is the generic exception returned by + producers if something didn't quite happen as expected during a method invocation. This means that + <literal>OperationFailedFault</literal> can be caused by several different reasons, one + of them being a request to modify the registration data. Please take a look at the log files to see + if you can gather more information as to what happened. WSRP 2 introduces an exception that is + specific to a request to modify registrations thus reducing the ambiguity that currently exists.</para> + </note> + </para> + </section> + </section> + + <section> + <title>Consumer operations</title> + <para> + Several operations are available from the consumer list view of the WSRP configuration portlet: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/consumer_operations.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + <para> + The available operations are: + <itemizedlist> + <listitem><para>Configure: displays the consumer details and allows user to edit them</para></listitem> + <listitem> + <para>Refresh: forces the consumer to retrieve the service description from the remote producer to refresh + the local information (offered portlets, registration information, etc.)</para> + </listitem> + <listitem><para> + Activate/Deactivate: activates/deactivates a consumer, governing whether it will be available to + provide portlets and receive portlet invocations</para> + </listitem> + <listitem><para> + Register/Deregister: registers/deregisters a consumer based on whether registration is required + and/or acquired</para> + </listitem> + <listitem><para>Delete: destroys the consumer, after deregisterting it if it was registered</para></listitem> + </itemizedlist> + </para> + </section> + + <section> + <title>Erasing local registration data</title> + <para> + There are rare cases where it might be required to erase the local information without being able to + deregister first. This is the case when a consumer is registered with a producer that has been modified by + its administrator to not require registration anymore. If that ever was to happen (most likely, it won't), + you can erase the local registration information from the consumer so that it can resume interacting with + the remote producer. To do so, click on "Erase local registration" button next to the registration context + information on the consumer configuration screen: + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/erase_registration.png" align="center" valign="middle"/> + </imageobject> + </mediaobject> + <para> + <emphasis>Warning:</emphasis> This operation is dangerous as it can result in inability to interact with the remote producer if invoked when not required. A warning screen will be displayed to give you a chance to change your mind: + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/erase_registration_warning.png" align="center" valign="middle"/> + </imageobject> + </mediaobject> + </section> + </section> + + <section id="producer_config"> + <title>Configuring JBoss Portal's WSRP Producer</title> + <section> + <title>Overview</title> + <para> + You can configure the behavior of Portal's WSRP Producer by using the WSRP administration interface, which + is the preferred way, or by editing the <filename>conf/config.xml</filename> file found in + <filename>portal-wsrp.sar</filename>. Several aspects can be modified with respects to whether + registration is required for consumers to access the Producer's services. An XML Schema for the configuration + format is available at <filename>jboss-portal.sar/portal-wsrp.sar/xsd/jboss-wsrp-producer_2_6.xsd</filename>, + while a (legacy) DTD is available at + <filename>jboss-portal.sar/portal-wsrp.sar/dtd/jboss-wsrp-producer_2_6.dtd</filename> + </para> + </section> + <section> + <title>Default configuration</title> + <para> + The default producer configuration is to require that consumers register with it before providing access its + services but does not require any specific registration properties (apart from what is mandated by the + WSRP standard). It does, however, require consumers to be registered before sending them a full service + description. This means that our WSRP producer will not provide the list of offered portlets and other + capabilities to unregistered consumers. The producer also uses the default + <classname>RegistrationPolicy</classname> paired with the default + <classname>RegistrationPropertyValidator</classname>. We will look into property + validators in greater detail later in <xref linkend="registration-configuration"/>. Suffice to say for now + that this allows users to customize how Portal's WSRP Producer decides whether a given registration property + is valid or not. + </para> + <para> + JBoss Portal 2.6.3 introduces a web interface to configure the producer's behavior. You can access it + by clicking on the "Producer Configuration" tab of the "WSRP" page of the "admin" portal. Here's what you + should see with the default configuration: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/producer_default.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + As would be expected, you can specify whether or not the producer will send the full service description to + unregistered consumers, and, if it requires registration, which <classname>RegistrationPolicy</classname> to + use (and, if needed, which <classname>RegistrationPropertyValidator</classname>), along with required + registration property description for which consumers must provide acceptable values to successfully + register. + </para> + </section> + + <section id="registration-configuration"> + <title>Registration configuration</title> + <para> + In order to require consumers to register with Portal's producer before interacting with it, you need to + configure Portal's behavior with respect to registration. Registration is optional, as are registration + properties. The producer can require registration without requiring consumers to pass any registration + properties as is the case in the default configuration. Let's configure our producer starting with a blank + state: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/producer_blank.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + We will allow unregistered consumers to see the list of offered portlets so we leave the first checkbox + ("Access to full service description requires consumers to be registered.") unchecked. We will, however, + specify that consumers will need to be registered to be able to interact with our producer. Check the second + checkbox ("Requires registration. Modifying this information will trigger invalidation of consumer + registrations."). The screen should now refresh and display: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/producer_registration.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + You can specify the fully-qualified name for your <classname>RegistrationPolicy</classname> and + <classname>RegistrationPropertyValidator</classname> there. We will keep the default value. See + <xref linkend="custom_registration"/> for more details. Let's add, however, a registration property called + <literal>email</literal>. Click "Add property" and enter the appropriate information in the fields, + providing a description for the registration property that can be used by consumers to figure out its + purpose: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/producer_email.png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + Press "Save" to record your modifications. + + <note><title>Note</title><para> + At this time, only String (xsd:string) properties are supported. If your application requires more + complex properties, please let us know.</para> + </note> + + <note><title>Note</title><para> + If consumers are already registered with the producer, modifying the configuration of required + registration + information will trigger the invalidation of held registrations, requiring consumers to modify their + registration before being able to access the producer again. We saw the consumer side of that process + in <xref linkend="reg_mod_error"/>.</para> + </note> + </para> + + <section id="custom_registration"> + <title>Customization of Registration handling behavior</title> + <para> + Registration handling behavior can be customized by users to suit their Producer needs. This is + accomplished by providing an implementation of the + <classname>RegistrationPolicy</classname> + interface. This interface defines methods that are called by Portal's Registration service so that + decisions can be made appropriately. A default registration policy that provides basic + behavior is provided and should be enough for most user needs. + </para> + <para> + While the default registration policy provides default behavior for most registration-related aspects, + there is still one aspect that requires configuration: whether a given value for a registration property + is acceptable by the WSRP Producer. This is accomplished by plugging a + <classname>RegistrationPropertyValidator</classname> + in the default registration policy. This allows users to define their own validation mechanism. + </para> + <para> + Please refer to the <trademark class="trade">Javadoc</trademark> for <classname>org.jboss.portal.registration.RegistrationPolicy</classname> + and <classname>org.jboss.portal.Registration.policies.RegistrationPropertyValidator</classname> for more + details on what is expected of each method. + </para> + <para>Defining a registration policy is required for the producer to be correctly configured. This is + accomplished by specifying the qualified class name of the registration policy. Since we anticipate that + most users will use the default registration policy, it is possible to provide the class + name of your custom property validator instead to customize the default registration policy behavior. + Note that property validators are only used by the default policy. + + <note><title>Note</title><para>Since the policy or the validator are defined via their class name and dynamically loaded, it is + important that you make sure that the identified class is available to the application server. One way + to accomplish that is to deploy your policy implementation as JAR file in your AS instance deploy + directory. Note also that, since both policies and validators are dynamically instantiated, they must + provide a default, no-argument constructor.</para> + </note> + </para> + </section> + </section> + <section id="strict-mode"> + <title>WSRP validation mode</title> + <para>The lack of conformance kit and the wording of the WSRP specification leaves room for differing + interpretations, resulting in interoperability issues. It is therefore possible to encounter issues when + using consumers from different vendors. We have experienced such issues and have introduced a way to relax + the validation that our WSRP producer performs on the data provided by consumers to help with + interoperability by accepting data that would normally be invalid. Note that we only relax our validation + algorithm on aspects of the specification that are deemed harmless such as invalid language codes. + </para> + <para> + By default, the WSRP producer is configured in strict mode. If you experience issues with a given consumer, + you might want to try to relax the validation mode. This is accomplished by unchecking the "Use strict WSRP + compliance." checkbox on the Producer configuration screen. + </para> + </section> + + </section> +</chapter> + <chapter id="security"> + <!-- <chapterinfo> + <author> + <firstname>Roy</firstname> + <surname>Russo</surname> + </author> + <author> + <firstname>Julien</firstname> + <surname>Viet</surname> + </author> + </chapterinfo>--> + <title>Security</title> + <section id="securing_objects"> + <title>Securing Portal Objects</title> + <para> + This section describes how to secure portal objects (portal instances, pages, and portlet instances), using the + JBoss + Portal *-object.xml descriptor OR portlet-instances.xml descriptor. View the User Guide for information on how + to secure objects using the + Management Portlet. + </para> + <para>Securing portal objects declaratively, is done through the *-object.xml ( + <xref linkend="desc_objectxml"/> + ), for Portal Instances and Pages, or the portlet-instances.xml ( + <xref linkend="desc_instancesxml"/> + ) for Portlet Instances. The portion you will be adding to each object is denoted by the + <emphasis>&lt;security-constraint&gt;</emphasis> + tag: + <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE deployments PUBLIC + "-//JBoss Portal//DTD Portal Object 2.6//EN" + "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd"> +<deployments> + <deployment> + <parent-ref>default</parent-ref> + <if-exists>overwrite</if-exists> + <properties/> + <page> + <page-name>MyPage</page-name> + <window> + <window-name>HelloWorldPortletPageWindow</window-name> + <instance-ref>HelloWorldPortletPageInstance</instance-ref> + <region>center</region> + <height>0</height> + </window> + <security-constraint> + <policy-permission> + <action-name>viewrecursive</action-name> + <unchecked/> + </policy-permission> + </security-constraint> + </page> + </deployment> +</deployments>]]></programlisting> + </para> + <para>The basic principle of the security mechanism is that everything is restricted unless you grant privileges. + You grant privilege on a portal node by adding a security constraint as explained here: + + <programlisting><![CDATA[<security-constraint> + <policy-permission> + <unchecked/> + <action-name>viewrecursive</action-name> + </policy-permission> +</security-constraint>]]></programlisting> + The example above will grant the view privilege to anyone (unchecked role) to the current object and any + child object recursively.</para> + <para> + The security contraint portion is worth taking a look at, in an isolated fashion. It allows you to + secure a specific window/page/portal-instance based on a user's role. + </para> + <para> + <emphasis role="bold">Role definition:</emphasis> + You must define a role that this security constraint will apply to. Possible values are: + </para> + <itemizedlist> + <listitem> + <para> <emphasis role="bold">&lt;unchecked/&gt;</emphasis> + Anyone can view this page.</para> + </listitem> + <listitem> + <para> <emphasis role="bold">&lt;role-name&gt;SOMEROLE&lt;/role-name&gt;</emphasis> + Access to this page is limited to the defined role.</para> + </listitem> + </itemizedlist> + <para> + <emphasis role="bold">Access Rights:</emphasis> + You must define the access rights given to the role defined. Possible values are: + </para> + <itemizedlist> + <listitem> + <para> <emphasis role="bold">view</emphasis> + Users can view the page.</para> + </listitem> + <listitem> + <para> <emphasis role="bold">viewrecursive</emphasis> + Users can view the page and child pages.</para> + </listitem> + <listitem> + <para><emphasis role="bold">personalize</emphasis> + Users are able to personalize the page's theme.</para> + </listitem> + <listitem> + <para> <emphasis role="bold">personalizerecursive</emphasis> + Users are able to personalize the page AND its children's pages themes.</para> + </listitem> + </itemizedlist> + + <note> + <title>Restricting access</title> + <para>Out of the box the default portal as a viewrecursive right for all the users, it means that whenever a page + is added, this page will be seen by any user. To restrict access to this page, the default portal security constraint + must be changed from viewrecursive to view, and viewrecursive security constraints must be added to its children + so that they can be viewed except the one you want to restrict access to.</para> + </note> + <para> + We provide three live samples of this descriptor, here + <xref linkend="desc_instancesxml"/> + , + <xref linkend="desc_example_page"/> + ,and + <xref linkend="desc_example_portal"/> + </para> + </section> + + <section id="security.security_cms"> + <title>Securing the Content Management System</title> + <para> + The JBoss Portal CMS system consists of a directory structure of Files organized unto their respective Folders. Both Files and Folders are + considered to be CMS resources that can be secured based on portal Roles and/or Users. + </para> + <para> + The following features are supported by the fine grained security system of Portal CMS: + <itemizedlist> + <listitem><para> + You can associate "Read", "Write", and "Manage" Permissions at the CMS node level. (Both Files and Folders are treated as CMS nodes)</para> + </listitem> + <listitem> + <para>The Permissions are propagated recursively down a folder hierarchy</para> + </listitem> + <listitem> + <para> Any Permissions specified explicitly on the CMS Node overrides the policy inherited via recursive propagation</para> + </listitem> + <listitem> + <para>You can manage the Permissions using the CMS Admin GUI tool via the newly added "Secure Node" feature</para> + </listitem> + </itemizedlist> + </para> + <para> + <table frame="all"> + <title> Portal CMS Permission Matrix: </title> + <tgroup cols="3" align="left" colsep="1"> + + <thead> + <row> + <entry align="center">Permissions</entry> + <entry align="center">Allowed Actions</entry> + <entry align="center">Implies</entry> + </row> + </thead> + <tbody> + <row> + <entry> Read </entry> + <entry> Read Contents of Folder, File and its versions </entry> + <entry> N/A </entry> + </row> + <row> + <entry> Write</entry> + <entry> Create and Update new Folder and File </entry> + <entry> Read Access </entry> + </row> + <row> + <entry> Manage </entry> + <entry> Delete/Copy/Move/Rename Folders and Files</entry> + <entry> Read and Write Access </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <section id="security.security_cms_configuration"> + <title>CMS Security Configuration</title> + <para> + The configuration for the CMS Security service is specified in the + <literal>jboss-portal.sar/portal-cms.sar/META-INF/jboss-service.xml</literal> + file. The portion of the configuration relevant for securing the CMS service is listed as follows: + <programlisting> + <![CDATA[ + <!-- CMS Authorization Security Service --> + <mbean + code="org.jboss.portal.cms.security.AuthorizationManagerImpl" + name="portal:service=AuthorizationManager,type=cms" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <attribute name="JNDIName">java:portal/cms/AuthorizationManager</attribute> + <depends optional-attribute-name="Provider" proxy-type="attribute"> + portal:service=AuthorizationProvider,type=cms + </depends> + </mbean> + <mbean + code="org.jboss.portal.cms.security.AuthorizationProviderImpl" + name="portal:service=AuthorizationProvider,type=cms" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <!-- + NOTE: cmsRootUserName denotes a single Portal user that has access to everything in the CMS. Denote this user + carefully and should be synonymous to the 'root' user in UNIX operating systems. By default: this value is the built-in + 'admin' user account. This can be changed to any other user account registered in your Portal + --> + <attribute name="CmsRootUserName">admin</attribute> + <depends optional-attribute-name="IdentityServiceController" proxy-type="attribute">portal:service=Module,type=IdentityServiceController</depends> + </mbean> + <!-- ACL Security Interceptor --> + <mbean + code="org.jboss.portal.cms.impl.interceptors.ACLInterceptor" + name="portal:service=Interceptor,type=Cms,name=ACL" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <attribute name="JNDIName">java:/portal/cms/ACLInterceptor</attribute> + <attribute name="CmsSessionFactory">java:/portal/cms/CMSSessionFactory</attribute> + <attribute name="IdentitySessionFactory">java:/portal/IdentitySessionFactory</attribute> + <attribute name="DefaultPolicy"> + <policy> + <!-- permissions on the root cms node --> + <criteria name="path" value="/"> + <permission name="cms" action="read"> + <role name="Anonymous"/> + </permission> + <permission name="cms" action="write"> + <role name="User"/> + </permission> + <permission name="cms" action="manage"> + <role name="Admin"/> + </permission> + </criteria> + <!-- permissions on the default cms node --> + <criteria name="path" value="/default"> + <permission name="cms" action="read"> + <role name="Anonymous"/> + </permission> + <permission name="cms" action="write"> + <role name="User"/> + </permission> + <permission name="cms" action="manage"> + <role name="Admin"/> + </permission> + </criteria> + <!-- permissions on the private/protected node --> + <criteria name="path" value="/default/private"> + <permission name="cms" action="manage"> + <role name="Admin"/> + </permission> + </criteria> + </policy> + </attribute> + <depends optional-attribute-name="AuthorizationManager" proxy-type="attribute"> + portal:service=AuthorizationManager,type=cms + </depends> + <depends>portal:service=Hibernate,type=CMS</depends> + <depends>portal:service=Module,type=IdentityServiceController</depends> + </mbean>]]> + </programlisting> + </para> + <section id="security.security_cms_configuration_superuser"> + <title>CMS Super User</title> + <para> + A CMS Super User is a designated Portal User Account that has access to all resources/functions in the CMS. It is a concept similar to the + super user concept in a Linux and UNIX security systems. This account should be carefully used and properly protected. By default, JBoss Portal designates the + built-in 'admin' user account as a CMS Super User. This can be changed by modifying the <emphasis>cmsRootUserName</emphasis> value in the + <literal>jboss-portal.sar/portal-cms.sar/META-INF/jboss-service.xml</literal> configuration. + <programlisting> + <![CDATA[ + <mbean + code="org.jboss.portal.cms.security.AuthorizationProviderImpl" + name="portal:service=AuthorizationProvider,type=cms" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <!-- + NOTE: cmsRootUserName denotes a single Portal user that has access to everything in the CMS. Denote this user + carefully and should be synonymous to the 'root' user in UNIX operating systems. By default: this value is the built-in + 'admin' user account. This can be changed to any other user account registered in your Portal + --> + <attribute name="CmsRootUserName">admin</attribute> + <depends optional-attribute-name="IdentityServiceController" proxy-type="attribute">portal:service=Module,type=IdentityServiceController</depends> + </mbean> + ]]> + </programlisting> + </para> + </section> + <section id="security.security_cms_configuration_securityconsole"> + <title>CMS Security Console</title> + <para> + The CMS Security Console is used to assign proper permissions to all the nodes/content in the CMS. Besides protection on CMS content, this console itself + needs to be secured against unauthorized acceess. Currently, the console can be accessed only by Portal users that are members of the specified Role. By default, + JBoss Portal uses the built-in <emphasis>Admin</emphasis> role to allow access to this security console. This can be customized by modifying the value of + <emphasis>defaultAdminRole</emphasis> option specified in <literal>jboss-portal.sar/conf/identity/standardidentity-config.xml</literal> + </para> + </section> + </section> + </section> + + <section id="security.security_authentication"> + <title>Authentication with JBoss Portal</title> + <para>JBoss Portal relies on Java Platform, Enterprise Edition (Java EE) for the authentication of users. The Java EE authentication has its advantages and drawbacks. The main motivation for using Java EE security is the integration with the application server and the operational environment in which the portal is deployed. The servlet layer provides already the authentication functionality and obviously it is not a responsibility of the portal. Whenever a user is authenticated by the servlet layer its security identity is propagated throughout the call stack in the different layers of the Java EE stack. The weaknesses are the lack of an explicit logout mechanism and the lack of dynamicity in the mapping of URL as security resources. However JBoss Portal improves that behavior when it is possible to do so.</para> + <section> + <title>Authentication configuration</title> + <para>JBoss Portal can be seen before all as a web application and therefore inherits all the configuration mechanisms + related to web applications. The main entry point of the whole portal is the <emphasis>jboss-portal.sar/portal-server.war</emphasis> + deployment which is the web application that defines and maps the portal servlet. Here you can configure various things + <itemizedlist> + <listitem><para>In the <emphasis>WEB-INF/web.xml</emphasis> you can change the authentication mode. The default + authentication mechanism uses the form based authentication, however you can change it to any of the + mechanism provided by the servlet specification.</para></listitem> +<listitem><para>In the <emphasis>WEB-INF/jboss-web.xml</emphasis> you can change the security domain used by the portal. + The default security domain used by the portal is <emphasis>java:/jaas/portal</emphasis>. That setting is specific + to the JBoss Application Server and how it binds the Java EE security to the operational environment. A security domain + is a scope defined at the Application Server Level and defines usually a JAAS authentication stack. The portal + security domain authentication stack is defined in the <emphasis>jboss-portal.sar/conf/login-config.xml</emphasis> + and is dynamically deployed with the portal. The JBoss Application Server documentation is certainly the best + reference for that topic.</para> + </listitem> + <listitem><para>The files <emphasis>login.jsp</emphasis> and <emphasis>error.jsp</emphasis> represent the pages used + the form based authentication process. More information can be found in any good servlet documentation.</para></listitem> + </itemizedlist> + </para> + </section> + <section> + <title>The portal servlet</title> + <para>The portal defines a single servlet to take care of all portal requests. The class name of that servlet is + <emphasis>org.jboss.portal.server.servlet.PortalServlet</emphasis>. That servlet needs to be declared two times with different + configurations otherwise the portal would not be able to know about some request details which are importants. + <itemizedlist> + <listitem><para><emphasis>PortalServletWithPathMapping</emphasis> is used for path mapping mappings.</para></listitem> + <listitem><para><emphasis>PortalServletWithDefaultServletMapping</emphasis> is used for the default servlet mapping.</para></listitem> + </itemizedlist> + The portal servlet is mapped four times with different semantics, the differences between the semantics are related to the transport layer. + Each one of those for mappings will have the same request meaning for the portal beside the transport aspect. By default + those mappings are + <itemizedlist> + <listitem><para><emphasis>/*</emphasis> : the default access, does not define any security constraint. This is the default + access that everybody uses.</para></listitem> + <listitem><para><emphasis>/sec/*</emphasis> : the secured access, requires https usage. It is triggered when + a portlet is defined as secure or when a secure portlet link is created. It requires the configuration + of the https connector in JBoss Web. The JBoss Application Server documentation provides more information + about it.</para></listitem> +<listitem><para><emphasis>/auth/*</emphasis> : the authenticated access, requires the user to be authenticated + to be used.</para></listitem> +<listitem><para><emphasis>/authsec/*</emphasis> : combine the two previous options into a single one.</para></listitem> + </itemizedlist> + Usually ones should not care much about those mappings as the portal will by itself switch to the most appropriate mapping. + </para> + </section> + </section> + + <section id="security_authorization"> + <title>Authorization with JBoss Portal</title> + <para>JBoss Portal defines a framework for authorization. The default implementation of that framework is based on + the Java Authorization Contract for Containers (JACC) which is implemented by <trademark class="trade">J2EE</trademark> 1.4 Application Servers. This section of + the documentation focuses on defining the framework and its usage and is not an attempt to define what authorization + is or is not because it is out of scope of this context. Instead we will try to straightforwardly describe the + framework and how it is used. No specific knowledge is expected about JACC although it is a recommended read.</para> + <section> + <title>The portal permission</title> + <para>The <emphasis>org.jboss.portal.security.PortalPermission</emphasis> object is used to describe a permission for the portal. It extends the <emphasis>java.security.Permission</emphasis> + class and any permission checked in the portal should extend the <emphasis>PortalPermission</emphasis> as well. That permission + adds two fields to the <emphasis>Permission</emphasis> class + <itemizedlist> + <listitem><para>uri : is a string which represents an URI of the resource described by the permission.</para></listitem> + <listitem><para>collection : an object of class <emphasis>org.jboss.portal.security.PortalPermissionCollection</emphasis> which + is used when the permission act as a container for other permissions. If that object exists then the uri field should be null + as a portal permission represents an uri or acts as a container in an exclusive manner.</para></listitem> + </itemizedlist> + </para> + </section> + <section> + <title>The authorization provider</title> + <para> + The <emphasis>org.jboss.portal.security.spi.provider.AuthorizationDomain</emphasis> is an interface which provides access to several services. + <programlisting> +public interface AuthorizationDomain +{ + String getType(); + DomainConfigurator getConfigurator(); + PermissionRepository getPermissionRepository(); + PermissionFactory getPermissionFactory(); +} + </programlisting> + <itemizedlist> + <listitem><para><emphasis>org.jboss.portal.security.spi.provider.DomainConfigurator</emphasis> provides configuration access + to an authorization domain. The authorization schema is very simple as it consists of bindings between URI, roles and permissions.</para></listitem> + <listitem><para><emphasis>org.jboss.portal.security.spi.provider.PermissionRepository</emphasis> provides runtime access to the authorization + domain. Usually it is used to retrieve the permissions for a specific role and URI. It is used at runtime by the framework + to take security decisions.</para></listitem> +<listitem><para><emphasis>org.jboss.portal.security.spi.provider.PermissionFactory</emphasis> is a factory to instantiate permissions + for the specific domain. It is used at runtime to create permissions objects of the appropriate type by the security framework.</para></listitem> + </itemizedlist> + </para> + </section> + <section> + <title>Making a programmatic security check</title> + <para>Making a security check is an easy thing as it consists in creating a permission of the appropriate type and + make a check against the <emphasis>org.jboss.portal.spi.auth.PortalAuthorizationManager</emphasis> service. That + service is used by the portal to make security checks. It is connected to the different authorization providers + in order to take decisions at runtime based on the type of the permission. Access to that service is done + through the <emphasis>org.jboss.portal.spi.auth.PortalAuthorizationManagerFactory</emphasis>. The factory + is a portal service which is usually injected in other services like that</para> + <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<server> + ... + <mbean + code='MyService" + name="portal:service=MyService"> + <depends + optional-attribute-name="PortalAuthorizationManagerFactory" + proxy-type="attribute">portal:service=PortalAuthorizationManagerFactory</depends> + ... + </mbean> + ... +</server>]]></programlisting> + <para>It can be injected in the servlet context of a war file in the file <emphasis>WEB-INF/jboss-portlet.xml</emphasis></para> + <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE portlet-app PUBLIC + "-//JBoss Portal//DTD JBoss Portlet 2.6//EN" + "http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd"> +<portlet-app> + ... + <service> + <service-name>PortalAuthorizationManagerFactory</service-name> + <service-class> + org.jboss.portal.security.spi.auth.PortalAuthorizationManagerFactory + </service-class> + <service-ref>:service=PortalAuthorizationManagerFactory</service-ref> + </service> + ... +</portlet-app>]]></programlisting> + <para>Here is an example of how a security check is made for a specific page</para> + <programlisting> +PortalAuthorizationManager pam = factory.getManager(); +PortalObjectId id = page.getId(); +PortalObjectPermission perm = new PortalObjectPermission(id, PortalObjectPermission.VIEW_MASK); +if (pam.checkPermission(perm) == false) +{ + System.out.println("Current user is not authorized to view page " + id); +}</programlisting> + </section> + <section> + <title>Configuring an authorization domain</title> + <para>Configuring a domain can be done through the <emphasis>DomainConfigurator</emphasis> interface</para> + <programlisting> +public interface DomainConfigurator +{ + Set getSecurityBindings(String uri); + void setSecurityBindings(String uri, Set securityBindings) + throws SecurityConfigurationException; + void removeSecurityBindings(String uri) throws SecurityConfigurationException; +}</programlisting> + <para>The various methods of that interface allows to configure security bindings for a given resource where + a resource is naturally identified by an URI. The <emphasis>org.jboss.portal.security.RoleSecurityBinding</emphasis> + object is an object which encapsulate a role name and a set of actions bound to this role. + </para> + <programlisting> +RoleSecurityBinding binding1 = new RoleSecurityBinding(Collections.singleton("view"), "Admin"); +RoleSecurityBinding binding2 = new RoleSecurityBinding(Collections.singleton("view"), "User"); +Set bindings = new HashSet(); +bindings.add(binding1); +bindings.add(binding2); +configurator.setSecurityBinding(pageURI, bindings); </programlisting> + </section> + </section> +</chapter> + <chapter id="identity"> + <!-- <chapterinfo> + <author> + <firstname>Boleslaw</firstname> + <surname>Dawidowicz</surname> + </author> + </chapterinfo>--> + <title>JBoss Portal Identity Management</title> + <para>This chapter addresses identity management in JBoss Portal 2.6</para> + <section id="management_api"> + <title>Identity management API</title> + <para>Since JBoss Portal 2.6 there are 4 identity services and 2 identity related interfaces. The goal of + having such a fine grained API is to enable flexible implementations based on different + identity storage like relational databases or LDAP servers. The Membership service takes care of managing the relationship + between user objects and role objects. The User Profile service is responsible for managing the profile of a user, + it has database and LDAP implementations as well as a mode that combines data from both. + </para> + <itemizedlist> + <listitem> + <para> + The <emphasis role="bold">org.jboss.portal.identity.User</emphasis> + interface represents a user and exposes the following operations: + + <programlisting><![CDATA[ + /** The user identifier. */ + public Object getId(); + + /** The user name. */ + public String getUserName(); + + /** Set the password using proper encoding. */ + public void updatePassword(String password); + + /** Return true if the password is valid. */ + public boolean validatePassword(String password); + ]]></programlisting> + <warning> + <para> + Important Note! The proper usage of getId() method is: + </para> + <programlisting><![CDATA[ +// Always use it like this: +user.getId().toString(); + +// Do not use it like this: + +// We would get a Long object if we are using the database implementation +(Long)user.getId(); + +// We would get a String with an LDAP server +(String)user.getId(); +]]></programlisting> + <para> + This is because the ID value depends on the User implementation. It'll probably be String object with the LDAP implementation and a Long object with the database implementation but it could be something else if one has chosen to make its own implementation. + </para> + </warning> + </para> + </listitem> + <listitem> + <para> + The <emphasis role="bold">org.jboss.portal.identity.Role</emphasis> interface represents a Role + and exposes the following operations: + + <programlisting><![CDATA[ +/** The role identifier. */ +public Object getId(); + +/** The role name used in security rules. This name can not be modified */ +public String getName(); + +/** The role display name used on screens. This name can be modified */ +public String getDisplayName(); + +/** */ +public void setDisplayName(String name); +]]></programlisting> + </para> + </listitem> + <listitem> + <para> + The <emphasis role="bold">org.jboss.portal.identity.UserModule</emphasis> + interface exposes operations for users management: + + <programlisting><![CDATA[ +/**Retrieve a user by its name.*/ +User findUserByUserName(String userName) + throws IdentityException, IllegalArgumentException, NoSuchUserException; + +/**Retrieve a user by its id.*/ +User findUserById(Object id) + throws IdentityException, IllegalArgumentException, NoSuchUserException; + +/**Retrieve a user by its id.*/ +User findUserById(String id) + throws IdentityException, IllegalArgumentException, NoSuchUserException; + +/** Creates a new user with the specified name.*/ +User createUser(String userName, String password) + throws IdentityException, IllegalArgumentException; + +/** Remove a user.*/ +void removeUser(Object id) + throws IdentityException, IllegalArgumentException; + +/** Get a range of users.*/ +Set findUsers(int offset, int limit) + throws IdentityException, IllegalArgumentException; + +/** Get a range of users.*/ +Set findUsersFilteredByUserName(String filter, int offset, int limit) + throws IdentityException, IllegalArgumentException; + +/**Returns the number of users.*/ +int getUserCount() throws IdentityException, IllegalArgumentException; +]]></programlisting> + </para> + </listitem> + <listitem> + <para> + The <emphasis role="bold">org.jboss.portal.identity.RoleModule</emphasis> + interface exposes operations for roles management: + + <programlisting><![CDATA[ +/** Retrieves a role by its name*/ +Role findRoleByName(String name) + throws IdentityException, IllegalArgumentException; + +/**Retrieve a collection of role from the role names.*/ +Set findRolesByNames(String[] names) + throws IdentityException, IllegalArgumentException; + +/** Retrieves a role by its id.*/ +Role findRoleById(Object id) + throws IdentityException, IllegalArgumentException; + +/** Retrieves a role by its id.*/ +Role findRoleById(String id) + throws IdentityException, IllegalArgumentException; + +/** Create a new role with the specified name.*/ +Role createRole(String name, String displayName) + throws IdentityException, IllegalArgumentException; + +/** Remove a role.*/ +void removeRole(Object id) + throws IdentityException, IllegalArgumentException; + +/** Returns the number of roles. */ +int getRolesCount() + throws IdentityException; + +/** Get all the roles */ +Set findRoles() throws IdentityException; +]]></programlisting> + </para> + </listitem> + <listitem> + <para> + The <emphasis role="bold">MembershipModule</emphasis> + interface exposes operations for obtaining or managing relationships beetween users and roles. + The role of this service is to decouple relationship information from user and roles. + Indeed while user role relationship is pretty straightforward with a relational database (using + a many to many relationship with an intermediary table), with an LDAP server there a different + ways to define relationships between users and roles. + + <programlisting><![CDATA[ +/** Return the set of role objects that a given user has.*/ +Set getRoles(User user) throws IdentityException, IllegalArgumentException; + +Set getUsers(Role role) throws IdentityException, IllegalArgumentException; + +/** Creates a relationship beetween a role and set of users. Other roles that have + assotiontions with those users remain unaffected.*/ +void assignUsers(Role role, Set users) throws IdentityException, IllegalArgumentException; + +/** Creates a relationship beetween a user and set of roles. This operation will erase any + other assotientions beetween the user and roles not specified in the provided set.*/ +void assignRoles(User user, Set roles) throws IdentityException, IllegalArgumentException; + +/** Returns role members based on rolename - depreciated method ethod here only + for compatibility with old RoleModule interface */ +Set findRoleMembers(String roleName, int offset, int limit, String userNameFilter) + throws IdentityException, IllegalArgumentException; +]]></programlisting> + </para> + </listitem> + <listitem> + <para> + The <emphasis role="bold">UserProfileModule</emphasis> + interface exposes operations to access and manage informations stored in User profile: + + <programlisting><![CDATA[ +public Object getProperty(User user, String propertyName) + throws IdentityException, IllegalArgumentException; + +public void setProperty(User user, String name, Object property) + throws IdentityException, IllegalArgumentException; + +public Map getProperties(User user) + throws IdentityException, IllegalArgumentException; + +public ProfileInfo getProfileInfo() + throws IdentityException; +]]></programlisting> + <warning> + <para> + UserProfileModule.getProperty() method returns an Object. + In most cases with DB backend it will always be String object. But normally you should check what + object will be retrieved using getProfileInfo() method.</para> + </warning> + </para> + </listitem> + <listitem> + <para> + The <emphasis role="bold">ProfileInfo</emphasis> + interface can be obtained using the + <emphasis role="bold">UserProfileModule</emphasis> + and exposes meta information of a profile: + + <programlisting><![CDATA[ +/** Returns a Map o PropertyInfo objects describing profile properties */ +public Map getPropertiesInfo(); + +public PropertyInfo getPropertyInfo(String name); +]]></programlisting> + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">PropertyInfo</emphasis> + interface expose methods to obtain information about accessible property in User profile + + <programlisting><![CDATA[ +public static final String ACCESS_MODE_READ_ONLY = "read-only"; +public static final String ACCESS_MODE_READ_WRITE = "read-write"; +public static final String USAGE_MANDATORY = "mandatory"; +public static final String USAGE_OPTIONAL = "optional"; +public static final String MAPPING_DB_TYPE_COLUMN = "column"; +public static final String MAPPING_DB_TYPE_DYNAMIC = "dynamic"; + +public String getName(); + +public String getType(); + +public String getAccessMode(); + +public String getUsage(); + +public LocalizedString getDisplayName(); + +public LocalizedString getDescription(); + +public String getMappingDBType(); + +public String getMappingLDAPValue(); + +public String getMappingDBValue(); + +public boolean isMappedDB(); + +public boolean isMappedLDAP(); +]]></programlisting> + </para> + </listitem> + + </itemizedlist> + + <section> + <title>How to obtain identity modules services ?</title> + <para> + The advocated way to get a reference to the identity modules is by using JNDI: + </para> + <programlisting> +import org.jboss.portal.identity.UserModule; +import org.jboss.portal.identity.RoleModule; +import org.jboss.portal.identity.MembershipModule; +import org.jboss.portal.identity.UserProfileModule; + +[...] + +(UserModule)new InitialContext().lookup("java:portal/UserModule"); +(RoleModule)new InitialContext().lookup("java:portal/RoleModule"); +(MembershipModule)new InitialContext().lookup("java:portal/MembershipModule"); +(UserProfileModule)new InitialContext().lookup("java:portal/UserProfileModule");</programlisting> + <para> + Another way to do this is, if you are fimiliar with JBoss Microkernel architecture is to + get the <emphasis role="bold">IdentityServiceController</emphasis> + mbean. You may want to inject it into your services like this: + </para> + <programlisting><![CDATA[ +<depends optional-attribute-name="IdentityServiceController" proxy-type="attribute"> + portal:service=Module,type=IdentityServiceController +</depends>]]></programlisting> + <para> + or simply obtain in your code by doing a lookup using + the <emphasis role="bold">portal:service=Module,type=IdentityServiceController</emphasis> + name. Please refer to the JBoss Application Server documentation if you want to learn more + about service MBeans. Once you obtained the object you can use it: + </para> + + <programlisting> +(UserModule)identityServiceController.getIdentityContext() + .getObject(IdentityContext.TYPE_USER_MODULE); + +(RoleModule)identityServiceController.getIdentityContext() + .getObject(IdentityContext.TYPE_ROLE_MODULE); + +(MembershipModule)identityServiceController.getIdentityContext() + .getObject(IdentityContext.TYPE_MEMBERSHIP_MODULE); + +(UserProfileModule)identityServiceController.getIdentityContext() + .getObject(IdentityContext.TYPE_USER_PROFILE_MODULE); + </programlisting> + + </section> + <section> + <title>API changes since 2.4</title> + <para>Because in JBoss Portal 2.4 there were only + <emphasis role="bold">UserModule</emphasis> + , + <emphasis role="bold">RoleModule</emphasis> + , + <emphasis role="bold">User</emphasis> + and + <emphasis role="bold">Role</emphasis> + interfaces some API usages changed. Here are the most important changes you will need to aply to your + code while migrating your aplication to 2.6: + </para> + <itemizedlist> + <listitem> + <para> + For the <emphasis role="bold">User</emphasis> interface: + + <programlisting><![CDATA[ +// Instead of: user.getEnabled() +userProfileModule.getProperty(user, User.INFO_USER_ENABLED); + +// Instead of: user.setEnabled(value) +userProfileModule.setProperty(user, User.INFO_USER_ENABLED, value); + +// In a similar way you should change rest of methods that are missing in User interface +// in 2.6 by the call to the UserProfileModule + +// Instead of: user.getProperties() +userProfileModule.getProperties(user); + +// Instead of: user.getGivenName() +userProfileModule.getProperty(user, User.INFO_USER_NAME_GIVEN); + +// Instead of: user.getFamilyName() +userProfileModule.getProperty(user, User.INFO_USER_NAME_FAMILY); + +// Instead of: user.getRealEmail() +userProfileModule.getProperty(user, User.INFO_USER_EMAIL_REAL); + +// Instead of: user.getFakeEmail() +userProfileModule.getProperty(user, User.INFO_USER_EMAIL_FAKE); + +// Instead of: user.getRegistrationDate() +userProfileModule.getProperty(user, User.INFO_USER_REGISTRATION_DATE); + +// Instead of: user.getViewRealEmail() +userProfileModule.getProperty(user, User.INFO_USER_VIEW_EMAIL_VIEW_REAL); + +// Instead of: user.getPreferredLocale() +userProfileModule.getProperty(user, User.INFO_USER_LOCALE); + +// Instead of: user.getSignature() +userProfileModule.getProperty(user, User.INFO_USER_SIGNATURE); + +// Instead of: user.getLastVisitDate() +userProfileModule.getProperty(user, User.INFO_USER_LAST_LOGIN_DATE);]]></programlisting> + </para> + </listitem> + <listitem> + <para> + The <emphasis role="bold">RoleModule</emphasis> interface: + + <programlisting><![CDATA[ +// Instead of +// RoleModule.findRoleMembers(String roleName, int offset, int limit, String userNameFilter) +// throws IdentityException; +membershipModule.findRoleMembers(String roleName, int offset, int limit, + String userNameFilter) + +// Instead of +// RoleModule.setRoles(User user, Set roles) throws IdentityException; +membershipModule.assignRoles(User user, Set roles) + +// Instead of +// RoleModule.getRoles(User user) throws IdentityException; +membershipModule.getRoles(User user)]]></programlisting> + </para> + </listitem> + </itemizedlist> + </section> + </section> + <section> + <title>Identity configuration</title> + <para>In order to understand identity configuration you need to understand its architecture. + Different identity services like UserModule, RoleModule and etc are just plain Java classes that are instantiated and exposed + by the portal. So an *example* of UserModule service could be a plain Java bean object that would be: + </para> + <itemizedlist> + <listitem> + <para><emphasis role="bold">Instantiated</emphasis> using reflection</para> + </listitem> + <listitem> + <para><emphasis role="bold">Initialized/Started</emphasis> by invoking some methods</para> + </listitem> + <listitem> + <para><emphasis role="bold">Registered/Exposed</emphasis> using JNDI and/or mbeans (JBoss Microkernel) services, so other services of the portal can use it</para> + </listitem> + <listitem> + <para><emphasis role="bold">Managed</emphasis> in the matter of lifecycle - so it'll be stopped and unregistered during portal shutdown</para> + </listitem> + </itemizedlist> + <para> + As you see from this point of view, configuration just specifies what Java class will be used and how it should be used by portal as a service. + </para> + <note><title>Note</title><para>We use JBoss Microcontainer internally to manage the sub system made of those components so if you are interested in implementing + custom services - look on the methods that are used by this framework.</para></note> + + <para> + In JBoss Portal we provide a very flexible configuration. It is very easy to rearrange and customize services, + provide alternative implementations, extend the existing ones or provide a custom identity model. + </para> + <para>To grasp the full picture of the configuration of identity services let's start from its root + component. Whole configuration and setup of identity components is done by the + <emphasis role="bold">IdentityServiceController</emphasis> service. It brings to life and registers all other services + such as UserModule, RoleModule, MembershipModule and UserProfileModule. + <emphasis role="bold">IdentityServiceController</emphasis> is defined in + <emphasis>jboss-portal.sar/META-INF/jboss-service.xml</emphasis> + </para> + + <programlisting><![CDATA[ +<mbean + code="org.jboss.portal.identity.IdentityServiceControllerImpl" + name="portal:service=Module,type=IdentityServiceController" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <depends>portal:service=Hibernate</depends> + <attribute name="JndiName">java:/portal/IdentityServiceController</attribute> + <attribute name="RegisterMBeans">true</attribute> + <attribute name="ConfigFile">conf/identity/identity-config.xml</attribute> + <attribute name="DefaultConfigFile">conf/identity/standardidentity-config.xml</attribute> +</mbean>]]></programlisting> + <para> + We can specify a few options here: + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">RegisterMBeans</emphasis> - defines if IdentityServiceController should + register components which are instantiated as mbeans + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">ConfigFile</emphasis> - defines the location of the main identity services configuration file. It describes and configures all the components like UserModule, RoleModule... that need to be instantiated + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">DefaultConfigFile</emphasis> - defines the location of the configuration file containing + the default values. For each component defined in <emphasis role="bold">ConfigFile</emphasis>, the IdentityServiceController + will obtain a set of default options from this file. That helps to keep the main main configuration file + simple, short and easy to read. Potentially it provides more powerful customizations. + </para> + </listitem> + </itemizedlist> + </para> + <section> + <title>Main configuration file architecture (identity-config.xml)</title> + <para> + The file describing portal identity services contains three sections: + </para> + <programlisting><![CDATA[ +<identity-configuration> + <datasources> + <!-- Datasources section --> + <datasource> ... </datasource> + <datasource> ... </datasource> + ... + </datasources> + <modules> + <!-- Modules section --> + <module> ... </module> + <module> ... </module> + ... + </modules> + <options> + <!-- Options section --> + <option-group> ... </option-group> + <option-group> ... </option-group> + ... + </options> +</identity-configuration>]]></programlisting> + <para>By default you can find it in <emphasis>jboss-portal.sar/conf/identity/identity-config.xml</emphasis></para> + <section> + <title>Datasources</title> + <para>This section defines datasource components. They will be processed and instantiated before components in + <emphasis role="bold">Module</emphasis> section, so they will be ready to serve them.</para> + + <note><title>Note</title> + <para>This section isn't used with Database configuration as in JBoss Portal services exposing Hibernate + are defined separately. It is used by LDAP configuration and we will use it as an example</para> + </note> + <programlisting><![CDATA[ +<datasource> + <name>LDAP</name> + <service-name>portal:service=Module,type=LDAPConnectionContext</service-name> + <class>org.jboss.portal.identity.ldap.LDAPConnectionContext</class> + <config> + <option> + <name>host</name> + <value>jboss.com</value> + </option> + <option> + <name>port</name> + <value>10389</value> + </option> + <option> + <name>adminDN</name> + <value>cn=Directory Manager</value> + </option> + <option> + <name>adminPassword</name> + <value>xxxxx</value> + </option> + + <!-- Other options here.... --> + + </config> +</datasource>]]></programlisting> +<note> + <title>Note</title> + <para>If you look into JBoss Portal configuration files you will find that <![CDATA[<service-name/> and <class/>]]> + are specified in <emphasis role="bold">DefaultConfigFile</emphasis> and not in <emphasis role="bold">ConfigFile</emphasis>. + So here is how it works: those two will be picked up from default configuration. The same rule is effective + for the options - additional options will be picked up from default configuration. What is linking configuration in those two files + is the <emphasis role="bold"><![CDATA[<name>]]></emphasis> tag.</para> + </note> + </section> + <section> + <title>Modules</title> + <para>Modules are core service components like UserModule, RoleModule and etc. </para> + <programlisting><![CDATA[ +<module> + <!--type used to correctly map in IdentityContext registry--> + <type>User</type> + <implementation>DB</implementation> + + <!--name of service and class for creating mbean--> + <service-name>portal:service=Module,type=User</service-name> + <class>org.jboss.portal.identity.db.HibernateUserModuleImpl</class> + + <!--set of options that are in the instantiated object--> + <config> + <option> + <name>sessionFactoryJNDIName</name> + <value>java:/portal/IdentitySessionFactory</value> + </option> + <option> + <name>jNDIName</name> + <value>java:/portal/UserModule</value> + </option> + </config> +</module>]]></programlisting> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">implementation</emphasis> - defines the scope under which + the configuration for different implementations of modules <emphasis role="bold">type</emphasis>s resides. + It enables to define the default options of the configuration of the different implementations of + same module types in one configuration file. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">type</emphasis> - must be unique name across all modules defined in the main + configuration file. This is important as module will be stored with such name within IdentityContext + registry at runtime. Standard names are used (User, Role, Membership, UserProfile). Together with + <emphasis role="bold">implementation</emphasis> will create unique pair within file with default configuration values. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">service-name</emphasis> - will be used for the name when registered as an MBean. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">class</emphasis> - Java class that will be use to instantiate the module. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">config</emphasis> - contains options related to this module + </para> + </listitem> + </itemizedlist> + <note><title>Note</title><para> + Here you can easily see the whole idea about having two config files - main one and the one with default values. + The above code snippet with User module comes from <emphasis role="bold">standardidentity-config.xml</emphasis>, so the file + that defines default configuration values. Because of this in the main configuration file the definition of + User module will be as short as: + <programlisting><![CDATA[ +<module> + <!--type used to correctly map in IdentityContext registry--> + <type>User</type> + <implementation>DB</implementation> + <config/> +</module>]]></programlisting> + As you can see we specify only the type and the implementation - all the other values (service-name, class and set of options) + are read from default configuration. But remember that you can still overwrite any of those values in the + main config simply by overriding them.</para> + </note> + + </section> + <section> + <title>Options</title> + <para>This section provides common options that are accessible by identity modules. We set options + here that may need to be shared. They are grouped, and can have many values:</para> + <programlisting><![CDATA[ +<options> +<!--Common options section--> +<option-group> + <group-name>common</group-name> + <option> + <name>userCtxDN</name> + <value>ou=People,dc=example,dc=com</value> + </option> + <option> + <name>uidAttributeID</name> + <value>uid</value> + </option> + <option> + <name>passwordAttributeID</name> + <value>userPassword</value> + </option> + <option> + <name>roleCtxDN</name> + <value>ou=Roles,dc=example,dc=com</value> + </option> + <option> + <name>ridAttributeId</name> + <value>cn</value> + </option> + <option> + <name>roleDisplayNameAttributeID</name> + <value>cn</value> + </option> + <option> + <name>membershipAttributeID</name> + <value>member</value> + </option> + <option> + <name>membershipAttributeIsDN</name> + <value>true</value> + </option> +</option-group> +<option-group> + <group-name>userCreateAttibutes</group-name> + <option> + <name>objectClass</name> + <value>top</value> + <value>uidObject</value> + <value>person</value> + <value>inetUser</value> + </option> + <!--Schema requires those to have initial value--> + <option> + <name>cn</name> + <value>none</value> + </option> + <option> + <name>sn</name> + <value>none</value> + </option> +</option-group>]]></programlisting> + <note> + <title>Note</title><para> + In this section we use the same inheritance mechanism. When an option is not set, its value will be read + from the default config file. But this also means that you may need to overwrite some values that + are specific to your LDAP architecture. All the options will be described along with module implementations + that use them.</para> + </note> + </section> + </section> + </section> + <section id="user_profile_configuration"> + <title>User profile configuration</title> + <para>UserProfileModule has additional configuration file that defines user properties. It is specified in configuration in:</para> + <programlisting> + <![CDATA[ + <module> + <type>UserProfile</type> + <implementation>DELEGATING</implementation> + + (...) + + <config> + + (...) + + <option> + <name>profileConfigFile</name> + <value>conf/identity/profile-config.xml</value> + </option> + </config> + </module> + ]]> + </programlisting> + <para>This means that you can configure user profile in <emphasis>jboss-portal.sar/conf/identity/profile-config.xml</emphasis></para> + + <programlisting> + <![CDATA[ +<profile> + + <property> + <name>user.name.nickName</name> + <type>java.lang.String</type> + <access-mode>read-only</access-mode> + <usage>mandatory</usage> + <display-name xml:lang="en">Name</display-name> + <description xml:lang="en">The user name</description> + <mapping> + <database> + <type>column</type> + <value>jbp_uname</value> + </database> + </mapping> + </property> + + <property> + <name>user.business-info.online.email</name> + <type>java.lang.String</type> + <access-mode>read-write</access-mode> + <usage>mandatory</usage> + <display-name xml:lang="en">Email</display-name> + <description xml:lang="en">The user real email</description> + <mapping> + <database> + <type>column</type> + <value>jbp_realemail</value> + </database> + <ldap> + <value>mail</value> + </ldap> + </mapping> + </property> + + <property> + <name>portal.user.location</name> + <type>java.lang.String</type> + <access-mode>read-write</access-mode> + <usage>optional</usage> + <display-name xml:lang="en">Location</display-name> + <description xml:lang="en">The user location</description> + <mapping> + <database> + <type>dynamic</type> + <value>portal.user.location</value> + </database> + </mapping> + </property> + + (...) + +</properties> + ]]> + </programlisting> + <para> Configuration file contains properties definition that can be retrieved using the <emphasis role="bold">PropertyInfo</emphasis> interface. + Each property used in portal has to be defined here.</para> + +<note><title>Note</title><para>Some information provided here can have a large impact on the behavior of the UserProfileModule. For instance + <emphasis>access-mode</emphasis> can be made read-only and the value provided in <emphasis>type</emphasis> will be checked + during <emphasis>setProperty()/getProperty()</emphasis> operations. On the other hand tags like <emphasis>usage</emphasis>, + <emphasis>description</emphasis> or <emphasis>display-name</emphasis> have mostly informational meaning at the moment and + are used by the management tools at runtime.</para></note> + + <itemizedlist> + <listitem><para> + <emphasis role="bold">name</emphasis> - property name. This value will be used to refer to the property in <emphasis>UserProfileModule</emphasis></para> + </listitem> + <listitem><para> + <emphasis role="bold">type</emphasis> - Java type of property. This type will be checked when in <emphasis>UserProfileModule</emphasis> + methods invocation.</para> + </listitem> + <listitem><para> + <emphasis role="bold">access-mode</emphasis> - possible values are <emphasis>read-write</emphasis> and <emphasis>read-only</emphasis></para> + </listitem> + + <listitem> + <para><emphasis role="bold">usage</emphasis> - property usage can be <emphasis>mandatory</emphasis> or <emphasis>optional</emphasis>.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">display-name</emphasis> - property display name.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">description</emphasis> - description of property.</para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">mapping</emphasis> - defines how property is mapped in the underlaying storage mechanism. It can be mapped in <emphasis>database</emphasis> + either as a <emphasis>column</emphasis> or <emphasis>dynamic</emphasis> value. It can also be mapped as <emphasis>ldap</emphasis> attribute. + + <note><title>Note</title><para>In current implementation <emphasis>column</emphasis> and <emphasis>dynamic</emphasis> mappings have the same effect, as database mappings are defined in hibernate configuration.</para></note> + + <note><title>Note</title> + <para>Property can have both <emphasis>ldap</emphasis> and <emphasis>database</emphasis> mappings. In such situation when LDAP support is enabled <emphasis>ldap</emphasis> mapping will take precedense. Also even when using LDAP some properties will be mapped to LDAP and some to database. Its because LDAP schema doesn't support all attributes proper to for portal properties. To solve this we have <emphasis role="bold">DelegatingUserProfileModuleImpl</emphasis> that will delegate method invocation to + <emphasis>ldap</emphasis> or <emphasis>database</emphasis> related <emphasis>UserProfile</emphasis> module. When <emphasis>LDAP</emphasis> support is enabled and property need to be stored in database user will be synchronized into database when needed. This behavior can be configured.</para> + </note> + </para> + </listitem> + </itemizedlist> + + + </section> + + <section> + <title>Identity modules implementations</title> + + <note><title>Note</title><para>Identity modules implementations related to LDAP are described in <xref linkend="ldap.ldap_identity_modules"/>. + </para></note> + <section> + <title>Database modules</title> + <para>JBoss portal comes with a set of database related identity modules implementations done using Hibernate - those are configured + by default. Those are not very + configurable in <emphasis>identity-config.xml</emphasis> file. The reason is that to keep backwards compatibility of database schema with previous + portal version, we reused most of hibernate implementation. If you want to tweak the hibernate mappings you should look into files in + <emphasis role="bold">jboss-portal.sar/conf/hibernate</emphasis>. Also those modules rely on hibernate <emphasis>SessionFactory</emphasis> components + that are created in <emphasis>SessionFactoryBinder</emphasis> mbeans defined in <emphasis>jboss-portal.sar/META-INF/jboss-service.xml</emphasis></para> + <para>Classes implementing identity modules: + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">org.jboss.portal.identity.db.HibernateUserModuleImpl</emphasis> - implementaing <emphasis>UserModule</emphasis> interface</para> + </listitem> + <listitem><para> + <emphasis role="bold">org.jboss.portal.identity.db.HibernateRoleModuleImpl</emphasis> - implementaing <emphasis>RoleModule</emphasis> interface</para> + </listitem> + <listitem><para> + <emphasis role="bold">org.jboss.portal.identity.db.HibernateMembershipModuleImpl</emphasis> - implementaing <emphasis>MembershipModule</emphasis> interface</para> + </listitem> + <listitem><para> + <emphasis role="bold">org.jboss.portal.identity.db.HibernateUserProfileModuleImpl</emphasis> - implementing <emphasis>UserProfileModule</emphasis> interface</para> + </listitem> + </itemizedlist> + </para> + <para>For each of those modules you can alter two config options: + <itemizedlist> + <listitem><para> + <emphasis>sessionFactoryJNDIName</emphasis> - JNDI name under which hibernate SessionFactory object is registered</para> + </listitem> + <listitem> + <para><emphasis>jNDIName</emphasis> - JNDI name under which this module should be registered</para> + </listitem> + </itemizedlist> + </para> + </section> + <section id="identity.management_api"> + <title>Delegating UserProfile module</title> + <para> + Delegating UserProfileModule implementation has very specific role. When we use a storage mechanism like LDAP we may not be able to map all + user properties into LDAP attributes because of schema limitations. To solve this problem we still can use the database to store user properties + that do not exist in the LDAP schema. + The Delegating user profile module will recognize if a property is mapped as <emphasis role="bold">ldap</emphasis> or <emphasis role="bold">database</emphasis> + and delegate <emphasis>setProperty()/getProperty()</emphasis> method invocation to proper module implementation. This is implemented in + <emphasis role="bold">org.jboss.portal.identity.DelegatingUserProfileModuleImpl</emphasis>. If property is mapped either as + <emphasis role="bold">ldap</emphasis> and <emphasis role="bold">database</emphasis> the <emphasis role="bold">ldap</emphasis> mapping will + have higher priority. + </para> + <programlisting> + <![CDATA[ +<module> + <!--type used to correctly map in IdentityContext registry--> + <type>UserProfile</type> + <implementation>DELEGATING</implementation> + + <!--name of service and class for creating mbean--> + <service-name>portal:service=Module,type=UserProfile</service-name> + <class>org.jboss.portal.identity.DelegatingUserProfileModuleImpl</class> + <!--set of options that are set in instantiated object--> + <config> + <option> + <name>jNDIName</name> + <value>java:/portal/UserProfileModule</value> + </option> + <option> + <name>dbModuleJNDIName</name> + <value>java:/portal/DBUserProfileModule</value> + </option> + <option> + <name>profileConfigFile</name> + <value>conf/identity/profile-config.xml</value> + </option> + </config> +</module>]]> + </programlisting> + <para> + Module options are: + <itemizedlist> + <listitem><para> + <emphasis role="bold">dbModuleJNDIName</emphasis> - JNDI name under which database implementation of UserProfileModule is registered.</para> + </listitem> + <listitem><para> + <emphasis role="bold">ldapModuleJNDIName</emphasis> - JNDI name under which ldap implementation of UserProfileModule is registered.</para> + </listitem> + <listitem><para> + <emphasis role="bold">profileConfigFile</emphasis> - configuration file for user properties.</para> + </listitem> + </itemizedlist> + </para> + </section> + <section> + <title>Database UserProfile module implementation</title> + <para>Because of the behavior described in the previous section, database UserProfileModule requires some special features. If a user is present in + LDAP server but a writable property isn't mapped as an LDAP attribute, such property requires to be stored in the database. In order to achieve + such result the user need to be synchronized from LDAP into the database first.</para> + <para>Class <emphasis>org.jboss.portal.identity.db.HibernateUserProfileModuleImpl</emphasis> has additional synchronization features. + Here are the options: </para> + + <itemizedlist> + <listitem><para> + <emphasis role="bold">synchronizeNonExistingUsers</emphasis> - when set to "true" if the user subject to the operation does not exist, then it will + created it in database. By default it is "true".</para> + </listitem> + <listitem><para> + <emphasis role="bold">acceptOtherImplementations</emphasis> - if set to "true" module will accept user objects other than + <emphasis>org.jboss.portal.identity.db.HibernateUserImpl</emphasis>. This is needed to enable cooperation with UserModule implementations other + than <emphasis>org.jboss.portal.identity.db.HibernateUserModuleImpl</emphasis>. The default value is set "true".</para> + </listitem> + <listitem> + <para><emphasis role="bold">defaultSynchronizePassword</emphasis> - if this option is set, the value will be used as a password for synchronized user.</para> + </listitem> + <listitem> + <para><emphasis role="bold">randomSynchronizePassword</emphasis> - if this option is set to "true" synchronized user will have random generated password. This is mostly used for the security reasons. Default value is "false".</para> + </listitem> + <listitem> + <para><emphasis role="bold">sessionFactoryJNDIName</emphasis> - JNDI name under which this user will be registered.</para> + </listitem> + <listitem> + <para><emphasis role="bold">profileConfigFile</emphasis> - file with user profile configuration. If this option is not set, and we use delegating UserProfileModule, profile configuration will be obtained from it.</para> + </listitem> + </itemizedlist> + + </section> + </section> +</chapter> + <chapter id="identityportlets"> +<!-- <chapterinfo> + <author> + <firstname>Emanuel</firstname> + <surname>Muckenhuber</surname> + </author> + </chapterinfo>--> + <title>JBoss Portal Identity Portlets</title> + <section id="identity_portlet_introduction"> + <title>Introduction</title> + <para> + Since JBoss Portal 2.6.2 two new Identity Portlets are + shipped by default: + <itemizedlist> + <listitem> + <para>The User Portlet</para> + </listitem> + <listitem> + <para>The Identity Management Portlet</para> + </listitem> + </itemizedlist> + As the names indicate - the User Portlet is responsible for + actions related to the end user. Whereas the Identity Management + Portlet contains all the functionality for managing users and roles. + </para> +<warning><title>Caution</title><para> +The Identity portlets will evolve over time, therefore usage and configuration might change.</para> +</warning> + <section> + <title>Features</title> + <para> + The identity portlets provide the following features: + <itemizedlist> + <listitem> + <para>Email verification: The users can receive an email with a link on which they must click to confirm the + creation of the new account. (Disabled by default,see <xref linkend="identity_portlet_configuration_jbpm"/>)</para> + </listitem> + <listitem> + <para>Captcha support: The users are prompted to copy letters from a deformed image. (Disabled by default, see <xref linkend="identity_portlet_configuration_captcha"/>)</para> + </listitem> + <listitem> + <para>Lost password: The users can receive a new password by email, any user with access to the admin portlet can also reset another user's password and send the new one by email in one click. (Disabled by default, see <xref linkend="identity_portlet_configuration_lost_password"/>)</para> + </listitem> + <listitem> + <para>jBPM based user registration: Several business processes are available out of the box (this includes administration approval), this can + be extended to custom ones. See <xref linkend="identity_portlet_configuration_jbpm"/>.</para> + </listitem> + <listitem> + <para>User and role management: Ability for the administrator to add and edit users as well as adding, </para> + </listitem> + </itemizedlist> + </para> + </section> + </section> + <section> + <title>Configuration</title> + <para> + This section covers the configuration of the Identity + Portlets. + </para> + <section id="identity_portlet_configuration_captcha"> + <title>Captcha support</title> + <para> + CAPTCHA is an acronym for <literal>Completely Automated Public + Turing test to tell Computers and Humans Apart</literal>. This is + providing a mechanism to prevent automated programs + from using different services. The User + Portlet uses JCaptcha to provide a challenge-response. + </para> + <note><para>By default the captcha service needs a XServer to + generate the images. For using the captcha service + without a XServer make sure you run the JVM with the + following option: + <programlisting>-Djava.awt.headless=true</programlisting></para> + </note> + <para/> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/identityportlets/user_register.png"/> + </imageobject> + + </mediaobject> + <para>The registration page with captcha.</para> + <para> + The captcha support can be enabled by changing the + portlet preference 'captcha' to 'true'. If enabled, + captcha will be used for the registration and lost + password action. + </para> + <programlisting><![CDATA[... +<portlet> +... + <display-name>User portlet</display-name> +... + <portlet-preferences> + <preference> + <name>captcha</name> + <value>true</value> + </preference> + </portlet-preferences> +</portlet> +...]]></programlisting> + </section> + <section id="identity_portlet_configuration_lost_password"> + <title>Lost password</title> + <para> + The lost password feature enables the end user to reset + his password by entering his username. + </para> + <note> + <title>Note</title><para>This feature requires a properly configured MailModule. See <xref linkend="emailConfiguration"/>.</para> + </note> + <para/> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/identityportlets/lost_password.png"/> + </imageobject> + + </mediaobject> + <para> + The lost password page with captcha enabled. + </para> + <para> + The lost password feature can be enabled by changing the + portlet preference 'lostPassword' to 'true'. If captcha + is enabled it will be also used for verifying the lost + password action. + </para> + <programlisting><![CDATA[... +<portlet> +... + <display-name>User portlet</display-name> +... + <portlet-preferences> + <preference> + <name>lostPassword</name> + <value>true</value> + </preference> + </portlet-preferences> +</portlet> +...]]></programlisting> + </section> + <section id="identity_portlet_configuration_reset_password"> + <title>Reset password</title> + <para> + The reset password feature is similar to the lost + password feature, but it is used in the User Management + Portlet to reset the password of a user. That means + changing the password of a user is slightly simplified, + because a random password will be generated and sent to + the users e-mail address. + </para> + <programlisting><![CDATA[... +<portlet> +... + <display-name>User management portlet</display-name> +... + <portlet-preferences> + <preference> + <name>resetPassword</name> + <value>true</value> + </preference> + </portlet-preferences> +</portlet> +...]]></programlisting> + </section> + <section id="identity_portlet_configuration_jbpm"> + <title>jBPM based user registration</title> + <para> + JBoss Portal supports three different subscription modes by default: + <itemizedlist> + <listitem> + <para>Automatic subscription (no jBPM required), the users can register and directly login.</para> + </listitem> + <listitem> + <para>E-Mail validation, the users need to click on a link sent by email before being able to login.</para> + </listitem> + <listitem> + <para>E-Mail validation and admin approval, the users need to validate their email, then an admin needs to + approve the newly created account.</para> + </listitem> + </itemizedlist> + </para> + <note><title>Note</title><para> + The subscription mode has to be defined in the configuration file as explained here: <xref linkend="identity_portlet_configuration_file"/>.</para> + </note> + <warning><title>Caution</title><para> + Make sure that the application server is restarted after re-deploying the Identity Portlets. This is required to make sure that + the registration and approval process works properly! </para> + </warning> + + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/identityportlets/pending_users.png"/> + </imageobject> + + </mediaobject> + <para> + Approve or reject pending registrations (<emphasis>jbp_identity_validation_approval_workflow</emphasis>). + </para> + </section> + <section id="identity_portlet_configuration_file"> + <title>The configuration file</title> + <para> + The Identity Portlets use some metadata which can be + easily changed in the main configuration file, which is + located at <literal>jboss-portal.sar/portal-identity.sar/conf/identity-ui-configuration.xml</literal> as shown here: + </para> + <programlisting><![CDATA[<identity-ui-configuration> + + <subscription-mode>automatic</subscription-mode> + <admin-subscription-mode>automatic</admin-subscription-mode> + <overwrite-workflow>false</overwrite-workflow> + <email-domain>jboss.org</email-domain> + <email-from&gt;no-reply(a)jboss.com&lt;/email-from&gt; + <password-generation-characters>a...Z</password-generation-characters> + <default-roles> + <role>User</role> + </default-roles> + + <!-- user interface components --> + <ui-components> + <ui-component name="givenname"> + <property-ref>user.name.given</property-ref> + </ui-component> + <ui-component name="familyname"> + <property-ref>user.name.family</property-ref> + </ui-component> + ... +</identity-ui-configuration>]]></programlisting> + <para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold"> + subscription-mode: + </emphasis> + defines the User Portlet registration process + <itemizedlist> + <listitem><para> + <emphasis>automatic:</emphasis> no validation nor approval (default)</para> + </listitem> + <listitem><para> + <emphasis>jbp_identity_validation_workflow:</emphasis> e-mail validation, no approval</para> + </listitem> + <listitem><para> + <emphasis>jbp_identity_validation_approval_workflow:</emphasis> e-mail validation and approval</para> + </listitem> + <listitem><para> + <emphasis>custom:</emphasis> Take a look at Customizing the workflow</para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold"> + admin-subscription-mode: + </emphasis> + jBPM process used in the User Management Portlet for creating users + <itemizedlist> + <listitem><para> + <emphasis>automatic:</emphasis> + no validation nor approval (default)</para> + </listitem> + <listitem><para> + <emphasis>jbp_identity_validation_workflow:</emphasis> + e-mail validation, no approval</para> + </listitem> + <listitem><para> + <emphasis>jbp_identity_validation_approval_workflow:</emphasis> + e-mail validation and approval</para> + </listitem> + <listitem><para> + <emphasis>custom:</emphasis> + Take a look at Customizing the + workflow</para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold"> + overwrite-workflow: + </emphasis> + if set to 'true' the workflow will be overwritten during the next startup (default: false) + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold"> + email-domain: + </emphasis> + e-mail domain used in the validation e-mail by the template (can be anything) + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">email-from:</emphasis> + e-mail fro field used by the validation e-mail + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold"> + password-generation-characters: + </emphasis> + characters to use to generate a random password + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold"> + default-roles: + </emphasis> + one or more default roles + <itemizedlist> + <listitem><para> + available element: <emphasis role="bold">role</emphasis></para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold"> + ui-components: + </emphasis> + Defines the available user interface components. Take a look at the next section + for further details. + </para> + </listitem> + </itemizedlist> + Due to the differentiation between subscription-mode and + admin-subscription-mode it is possible to require e-mail + validation and approval for new registrations and e-mail + validation only when a user is created in the user + management portlet. + </para> + </section> + <section> + <title>Customize e-mail templates</title> + <para> + The email templates can be found in the folder: <emphasis>portal-identity.sar/conf/templates/</emphasis> + </para> + <para> + New languages can be added by creating a new file like: <emphasis>emailTemplate_fr.tpl</emphasis> + </para> + </section> + </section> + <section id="identity_portlet_configuration_ui_components"> + <title>User interface customization</title> + <para> + The following three examples describe common use cases for customizing the User Portlet. + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">Example 1:</emphasis> + Describes how to tag a input field as required + and add it to the registration page. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Example 2:</emphasis> + Shows how to create a simple dropdown menu. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Example 3:</emphasis> + Describes how to add new properties. + </para> + </listitem> + </itemizedlist> + </para> + <note> + <title>Note</title><para>This is not a JavaServer Faces tutorial. Basic knowledge of + this technology is a precondition for customizing the User + Portlet Interface.</para> + </note> + <section id="identity_portlet_configuration_example1"> + <title>Example 1: required fields</title> + <para> + This example explains how to change optional properties to + required properties, of course once this is done, we will also need to + add the corresponding fields in the registration page. + <!-- sbr/ --> + Here are the modifications in <emphasis>portal-identity.sar/conf/identity-ui-configuration.xml</emphasis>, + we simply changed the required element to true on our two fields corresponding to the given and family names. + </para> + <programlisting><![CDATA[<identity-ui-configuration> +... + <!-- user interface components --> + ... + <ui-component name="givenname"> + <property-ref>user.name.given</property-ref> + <required>true</required> + </ui-component> + <ui-component name="familyname"> + <property-ref>user.name.family</property-ref> + <required>true</required> + </ui-component> + ... +</identity-ui-configuration>]]></programlisting> + <para> + Now that we changed those values to "required" we need to give a chance to the user to enter those + values, here are the changes done in <emphasis>portal-identity.sar/portal-identity.war/WEB-INF/jsf/common/register.xhtml</emphasis> + </para> + <programlisting><![CDATA[ +... + <h:outputText value="#{bundle.IDENTITY_GIVENNAME}"/> + <h:inputText id="givenname" value="#{manager.uiUser.attribute.givenname}" + required="#{metadataservice.givenname.required}"/> + <h:panelGroup /> + <h:message for="givenname" /> + + <h:outputText value="#{bundle.IDENTITY_FAMILYNAME}"/> + <h:inputText id="lastname" value="#{manager.uiUser.attribute.familyname}" + required="#{metadataservice.familyname.required}"/> + <h:panelGroup /> + <h:message for="lastname"/> +...]]></programlisting> + <para> + That's it - from now on the given name and family name will be + required on registration. + We dynamically obtain the values from the descriptor. Now if i just wanted to make them back to optional, + i would change the values only in the descriptor, letting the user enter or not those values. + </para> + </section> + <section id="identity_portlet_configuration_example2"> + <title> + Example 2: dynamic values (dropdown menu with predefined values) + </title> + <para> + If the data to enter is a choice instead of a free-text value, you can also define those + in the descriptor like shown here: + </para> + <programlisting><![CDATA[<identity-ui-configuration> +... + <!-- user interface components --> + ... + <ui-component name="interests"> + <property-ref>portal.user.interests</property-ref> + <values> + <value key="board">snowboarding</value> + <value key="ski">skiing</value> + <value key="sledge">sledging</value> + </values> + </ui-component> + ... +</identity-ui-configuration>]]></programlisting> + <para> + <emphasis> + In portal-identity.sar/portal-identity.war/WEB-INF/jsf/common/profile.xhtml + </emphasis> + - change inputText to a selectOneMenu: + </para> + <programlisting><![CDATA[ + ... + <h:outputText value="#{bundle.IDENTITY_INTERESTS}"/> + <h:selectOneMenu id="interests" value="#{manager.uiUser.attribute.interests}" + required="#{metadataservice.interests.required}"> + <f:selectItems value="#{metadataservice.interests.values}" /> + </h.selectOneMenu> + <h:panelGroup /> + <h:message for="interests"/> +... +]]></programlisting> + <para> + For localizing dynamic values it is also possible to use the resource bundle. + This can be done by adding the key with a prefix (to i.e. <emphasis>Identity.properties</emphasis>) like in the following listing. + The key will be stored in the users property and is used to identify the element. The value of the configuration file will only be used if no localization information is found. + </para> + <programlisting><![CDATA[ +... +IDENTITY_DYNAMIC_VALUE_BOARD=localized snowboarding +IDENTITY_DYNAMIC_VALUE_SKI=localized skiing +IDENTITY_DYNAMIC_VALUE_SLEDGE=localized sledging +... +]]></programlisting> + <note> + <para>If the value is not required a blank element will be + added at the top.</para> + </note> + </section> + <section id="identity_portlet_configuration_example3"> + <title>Example 3: adding new properties</title> + <note> + <title>Note</title><para>Please make sure you read at least the section about + user profile configuration: <xref linkend="user_profile_configuration"/>, to add a new value on + the interface it also has to be defined in your model, as shown on Step 1.</para> + </note> + <para> + <emphasis role="bold">step 1:</emphasis> + add a new property to <emphasis>profile-config.xml</emphasis> e.g. a dynamic property called gender: + </para> + <programlisting><![CDATA[ +... + <property> + <name>user.gender</name> + <type>java.lang.String</type> + <access-mode>read-write</access-mode> + <usage>optional</usage> + <display-name xml:lang="en">Gender</display-name> + <description xml:lang="en">The gender</description> + <mapping> + <database> + <type>dynamic</type> + <value>user.gender</value> + </database> + </mapping> + </property> +... +]]></programlisting> + <note> + <title>Note</title><para>It is recommended to use the 'User Information Attribute Names' from the <ulink url="http://jcp.org/en/jsr/detail?id=168">Portlet Specification</ulink> for defining properties.</para> + </note> + <para> + <emphasis role="bold">step 2:</emphasis> + add the property to the identity-ui-configuration: (<emphasis>portal-identity.sar/conf/identity-ui-configuration.xml</emphasis>) + </para> + <programlisting><![CDATA[ +... + <ui-component name="gender"> + <property-ref>user.gender</property-ref> + <required>true</required> + <values> + <value key="male">Male</value> + <value key="female">Female</value> + </values> + </ui-component> +... +]]></programlisting> + <note> + <title>Note</title><para>The property-ref must match a property from the + <emphasis>profile-config.xml</emphasis>.</para> + </note> + <para> + <emphasis role="bold">step 3:</emphasis> + add your custom ui-component to the profile page: (<emphasis>portal-identity.sar/portal-identity.war/WEB-INF/jsf/profile.xhtml</emphasis>) + </para> + <programlisting><![CDATA[ +... + <h:outputText value="#{bundle.IDENTITY_GENDER}"/> + <h:selectOneMenu id="gender" value="#{manager.uiUser.attribute.gender}" + required="#{metadataservice.gender.required}"> + <f:selectItems value="#{metadataservice.gender.values}" /> + </h.selectOneMenu> + <h:panelGroup /> + <h:message for="gender"/> +... +]]></programlisting> + +<note><title>Note</title><para>Don't forget to add the localization elements.</para></note> + +</section> + <section> + <title>Illustration</title> + <para> + + </para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/identityportlets/illustration.png" scalefit="1"/> + </imageobject> + + </mediaobject> + <para> + Illustration of the relationship between the + configuration files. + </para> + <para> + The JSF-View in more detail: +<itemizedlist> + <listitem> + <para> + <emphasis role="bold"> manager.uiUser.attribute:</emphasis> + manages and stores the dynamic properties + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">examples:</emphasis> <emphasis>manager.uiUser.attribute.gender</emphasis>, + <emphasis>manager.uiUser.attribute.interests</emphasis> + <programlisting><![CDATA[<h:inputText id="gender" value="#{manager.uiUser.attribute.gender}" />]]></programlisting> + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold"> + metadataservice + </emphasis> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold"> + required + </emphasis> + - references the required attribute from the ui-component<!-- sbr/ --> + example: <emphasis>metadataservice.gender.required</emphasis> + <programlisting><![CDATA[<h:inputText id="gender" value="#{manager.uiUser.attribute.gender}" required="#{metadataservice.gender.required}"/>]]></programlisting> + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold"> + values + </emphasis> + - references the values list from the ui-component<!-- sbr/ --> + example: <emphasis>metadataservice.gender.values</emphasis> + <programlisting><![CDATA[<h:selectOneMenu id="interests" value="#{manager.uiUser.attribute.interests}"> + <f:selectItems value="#{metadataservice.interests.values}" /> +</h:selectOneMenu>]]></programlisting> + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold"> + validator + </emphasis> + - references the name of a registered JSF validator<!-- sbr/ --> + example:<emphasis>metadataservice.gender.validator</emphasis> + - the first validator of the validator list<!-- sbr/ --> + example: <emphasis>metadataservice.gender.validators[0]</emphasis> + - the validator list with an index<!-- sbr/ --> + <programlisting><![CDATA[<f:validator validatorId="#{metadataservice.gender.validator}"/>]]></programlisting> + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold"> + converter + </emphasis> + - references the name of a registered JSF converter<!-- sbr/ --> + example: <emphasis>metadataservice.gender.converter</emphasis> + <programlisting><![CDATA[<f:converter converterId="#{metadataservice.gender.converter}"/>]]></programlisting> + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold"> + readOnly + </emphasis> + - references the access-mode of <emphasis>profile-config.xml</emphasis><!-- sbr/ --> + possible usage i.e. in <emphasis>/WEB-INF/jsf/common/profile.xhtml</emphasis> + <programlisting><![CDATA[<h:inputText value="#{manager.uiUser.attribute.nickname}" disabled="#{metadataservice.nickname.readOnly}" />]]></programlisting> + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </para> + <warning> + <para>The values of the profile-config.xml have a higher + priority than the values in the user portlet + configuration. That means if the 'usage' is 'mandatory' + in <emphasis>profile-config.xml</emphasis> + and 'required' is 'false' it will be overwritten by the + value from the profile config!</para> + </warning> + </section> + <section> + <title>Customizing the View Profile page</title> + <para> + By default not all values of the user profile will be displayed on the <emphasis>View profile</emphasis> page. For customization it is possible + to add further properties to the page by editing the file: <emphasis>portal-identity.sar/portal-identity.war/WEB-INF/jsf/profile/viewProfile.xhtml</emphasis> + </para> + </section> + </section> + <section> + <title>Customizing the workflow</title> + <note><para>For more details about jBPM please read the <ulink url="http://docs.jboss.com/jbpm/v3/userguide/index.html">jBPM documentation</ulink></para></note> + <para> + The process definitions are located in: + <emphasis>portal-identity.sar/conf/processes</emphasis>. To create a custom workflow, you can extend the existing process description file: <emphasis>custom.xml</emphasis>. + </para> + <para> + Available variables in the business process: + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">name:</emphasis> + portalURL + <!-- sbr/ --> + <emphasis role="bold">type:</emphasis> + <emphasis>java.lang.String</emphasis> + <!-- sbr/ --> + <emphasis role="bold">description:</emphasis> + represents the full url of the portal e.g. + <emphasis> + http://localhost:8080/portal + </emphasis> + <!-- sbr/ --> + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">name:</emphasis> + locale + <!-- sbr/ --> + <emphasis role="bold">type:</emphasis> + <emphasis>java.util.Locale</emphasis> + <!-- sbr/ --> + <emphasis role="bold">description:</emphasis> + the requested locale at registration + <!-- sbr/ --> + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">name:</emphasis> + email + <!-- sbr/ --> + <emphasis role="bold">type:</emphasis> + <emphasis>java.lang.String</emphasis> + <!-- sbr/ --> + <emphasis role="bold">description:</emphasis> + the e-mail address of the user in case of registration.<!-- sbr/ --> + In case of changing the e-mail the new e-mail address. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">name:</emphasis> + user + <!-- sbr/ --> + <emphasis role="bold">type:</emphasis> + <emphasis> + org.jboss.portal.core.identity.services.workflow.UserContainer + </emphasis> + <!-- sbr/ --> + <emphasis role="bold">description:</emphasis> + Seralizable Object containing user information through the jBPM process <!-- sbr/ --> + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">name:</emphasis> + validationHash + <!-- sbr/ --> + <emphasis role="bold">type:</emphasis> + <emphasis>java.lang.String</emphasis> + <!-- sbr/ --> + <emphasis role="bold">description:</emphasis> + hash used for the validation part. Only available after executing SendValidationEmailAction<!-- sbr/ --> + </para> + </listitem> + </itemizedlist> + </para> + <note><title>Note</title><para> + Make sure that the filename and the process name match! e.g. + <emphasis>conf/processes/custom.xml</emphasis> + and process-definition name="custom".</para> + </note> + <para> + When using a custom workflow it is possible to customize the + status message after registering in the locale bundle: ( e.g. + <emphasis>portal-identity.sar/conf/bundles/Identity.properties</emphasis>) + </para> + <programlisting><![CDATA[ + +IDENTITY_VERIFICATION_STATUS_REGISTER_CUSTOM=Customized message here + +]]></programlisting> + <section> + <title>Duration of process validity</title> + <para> + By default requests (e.g. e-mail validation and registrations) expire after some time in the validation state. + Therefore it is not required to add additional maintenance mechanism to invalidate a request. The default expiration time is 2 days, + but is quite easy to change the timing by editing the <emphasis>duedate</emphasis> attribute in the process definition. + changes in: <emphasis>portal-identity.sar/conf/processes/*.xml</emphasis> + </para> + <programlisting><![CDATA[<process-definition> +... + <state name="validate_email"> + <timer name="time_to_expire" duedate="2 days" transition="timedOut" /> + </state> +... +</process-definition>]]></programlisting> + + <para> + For further information take a look at the <ulink url="http://docs.jboss.com/jbpm/v3/userguide/index.html">jBPM documentation</ulink> on <emphasis>Duration</emphasis>. + </para> + </section> +</section> + <section> + <title>Disabling the Identity Portlets</title> + <para> + Due to the fact that the former user portlets are still + included in JBoss Portal 2.6.2 it is possible to activate + it in the Portal Admin interface, by using the PortletInstances: + <itemizedlist> + <listitem><para> + <emphasis>UserPortletInstance:</emphasis> The former user portlet</para> + </listitem> + <listitem><para> + <emphasis>RolePortletInstance:</emphasis> The former role managment portlet</para> + </listitem> + </itemizedlist> + </para> + <section> + <title>Enabling the Identity Portlets</title> + <para> + When migrating from former versions of JBoss Portal the Identity User Portlets won't be displayed by default, + but windows can be created on basis of the existing Portlet Instances which are deployed by default. (The instances + names being <literal>IdentityUserPortletInstance</literal> and <literal>IdentityAdminPortletInstance</literal>.) + </para> + </section> + </section> +</chapter> + <chapter id="authentication"> + <!-- <chapterinfo> + <author> + <firstname>Boleslaw</firstname> + <surname>Dawidowicz</surname> + </author> + </chapterinfo>--> + <title>Authentication and Authorization</title> + <para>This chapter describes the authentication mechanisms in JBoss Portal</para> + <section id="authentication_in_portal"> + <title>Authentication in JBoss Portal</title> + <para>JBoss Portal is heavily standard based so it leverages <emphasis>Java Authentication and Authorization Service (JAAS)</emphasis> + in JBoss Application Server. Because of this it can be configured in a very flexible manner and other + authentication solutions can be plugged in easily. + To better understand authentication mechanisms in JBoss Portal please refer to + <xref linkend="security.security_authentication"/>. + To learn more about JAAS look for proper documentation on + <ulink url="http://java.sun.com/javase/6/docs/technotes/guides/security/&qu... Security</ulink> website. + To learn more about security in JBoss Application Server please read + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossSX">JBoss... documentation. + </para> + <section id="authentication_configuration"> + <title>Configuration</title> + <para>You can configure the JAAS authentication stack in <emphasis>jboss-portal.sar/conf/login-config.xml</emphasis>. + It is important to remember that authorization in portal starts at the JAAS level - + configured <emphasis>LoginModule</emphasis>s apply proper <emphasis>Principal</emphasis> objects representing + the roles of authenticated user. As you can see in <emphasis>jboss-portal.sar/portal-server.war/WEB-INF/web.xml</emphasis> portal + servlet is secured with specified role ("<emphasis>Authenticated</emphasis>"). In the default portal configuration + this role is dynamically added by <emphasis>IdentityLoginModule</emphasis>. If you reconfigure the default JAAS authentication + chain with other <emphasis>LoginModule</emphasis> implementations, you should remember that you must deal with that + security constraints in order to be able to access portal. For example if you place only one <emphasis>LoginModule</emphasis> + that will authenticate users against LDAP server you may consider adding all users in your LDAP tree to such role. + </para> + </section> + </section> + <section id="portal_login_modules"> + <title>JAAS Login Modules</title> + <para>JBoss Portal comes with a few implementations of JAAS <emphasis>LoginModule</emphasis> interface</para> + <section> + <title>org.jboss.portal.identity.auth.IdentityLoginModule</title> + <para>This is the standard portal LoginModule implementation that uses portal identity modules in order to search users and roles. + By default it is the only configured LoginModule in the portal authentication stack. Its behavior can be altered with the following options: + <itemizedlist> + <listitem><para> + <emphasis role="bold">userModuleJNDIName</emphasis> - JNDI name of portal UserModule.</para> + </listitem> + <listitem><para> + <emphasis role="bold">roleModuleJNDIName</emphasis> - JNDI name of portal RoleModule.</para> + </listitem> + <listitem><para> + <emphasis role="bold">membershipModuleJNDIName</emphasis> - JNDI name of portal MembershipModule.</para> + </listitem> + <listitem><para> + <emphasis role="bold">additionalRole</emphasis> - additional user <emphasis>Principal</emphasis> that will be added to user <emphasis>Subject</emphasis>. + This is important as in default portal configuration it is the role that portal servlet is secured with.</para> + </listitem> + <listitem><para> + <emphasis role="bold">havingRole</emphasis> - only users belonging to role specified with this option will be authenticated.</para> + </listitem> + <listitem><para> + <emphasis role="bold">unauthenticatedIdentity</emphasis> - the principal to use when a null username and password are seen.</para> + </listitem> + </itemizedlist> + <note><title>Note</title><para>IdentityLoginModule extends org.jboss.security.auth.spi.UsernamePasswordLoginModule so if you are familiar with JBossSX you can apply + few other options like "password-stacking". Please refer to JBossSX documentation.</para></note> + </para> + </section> + <section> + <title>org.jboss.portal.identity.auth.DBIdentityLoginModule</title> + <para>This <emphasis>LoginModule</emphasis> implementation extends JBossSX <emphasis>org.jboss.security.auth.spi.DatabaseServerLoginModule</emphasis> and can be + used to authenticate against Database. The main purpose of this module is to be configured directly against portal database (instead of using portal identity + modules like in IdentityLoginModule). So if you are using custom LoginModule implementation you can place this module with "sufficient" flag. This can + be extremely useful. For example if you authenticate against LDAP server using JBossSX <emphasis>LdapLoginModule</emphasis> you can + fallback to users present in portal database and not present in LDAP like "admin" user. Please look into + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=DatabaseServerLoginMod... wiki page to learn more about + <emphasis>DatabaseServerLoginModule</emphasis> configuration</para> + <para> + Options are: + <itemizedlist> + <listitem><para> + <emphasis role="bold">dsJndiName</emphasis> - The name of the DataSource of the database containing the Principals and Roles tables</para> + </listitem> + <listitem><para> + <emphasis role="bold">principalsQuery</emphasis> - The prepared statement query, equivalent to: <emphasis>"select Password from Principals where PrincipalID=?"</emphasis></para> + </listitem> + <listitem><para> + <emphasis role="bold">rolesQuery</emphasis> - The prepared statement query, equivalent to: <emphasis>"select Role, RoleGroup from Roles where PrincipalID=?"</emphasis></para> + </listitem> + <listitem><para> + <emphasis role="bold">hashAlgorithm</emphasis> - The name of the <emphasis>java.security.MessageDigest</emphasis> algorithm to use to hash the password. + There is no default so this option must be specified to enable hashing. When hashAlgorithm is specified, the clear text password obtained from the <emphasis>CallbackHandler</emphasis> + is hashed before it is passed to UsernamePasswordLoginModule.validatePassword as the inputPassword argument. The expectedPassword as stored in the users.properties + file must be comparably hashed.</para> + </listitem> + <listitem><para> + <emphasis role="bold">hashEncoding</emphasis> - The string format for the hashed pass and st be either "base64" or "hex". Base64 is the default.</para> + </listitem> + <listitem><para> + <emphasis role="bold">additionalRole</emphasis> - additional user <emphasis>Principal</emphasis> that will be added to user <emphasis>Subject</emphasis>.</para> + </listitem> + </itemizedlist> + </para> + <para> + Configuration using portal database will look like this: + <programlisting> + <![CDATA[ +<login-module code = "org.jboss.portal.identity.auth.DBIdentityLoginModule" + flag="sufficient"> + <module-option name="dsJndiName">java:/PortalDS</module-option> + <module-option name="principalsQuery"> + SELECT jbp_password FROM jbp_users WHERE jbp_uname=? + </module-option/> + <module-option name="rolesQuery"> + SELECT jbp_roles.jbp_name, 'Roles' FROM jbp_role_membership INNER JOIN + jbp_roles ON jbp_role_membership.jbp_rid = jbp_roles.jbp_rid INNER JOIN jbp_users ON + jbp_role_membership.jbp_uid = jbp_users.jbp_uid WHERE jbp_users.jbp_uname=? + </module-option> + <module-option name="hashAlgorithm">MD5</module-option> + <module-option name="hashEncoding">HEX</module-option> + <module-option name="additionalRole">Authenticated</module-option> +</login-module> + ]]> + </programlisting> + + <note><title>Note</title><para>SQL query should be in single line. This code snipped was formatted like this only to fit documentation page.</para></note> + </para> + </section> + <section> + <title>org.jboss.portal.identity.auth.SynchronizingLdapLoginModule</title> + <para> + This module can be used instead of the IdentityLoginModule to bind to LDAP. + <emphasis>org.jboss.portal.identity.auth.SynchronizingLDAPLoginModule</emphasis> class is a wrapper around + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=LdapLoginModule"&... from JBossSX. + It extends it so all configuration that can be applied to <emphasis>LdapExtLoginModule</emphasis> remains valid here. For a user that + was authenticated successfully it will try to call the identity modules from portal, then check if such user + exists or not, and if does not exist it will try to create it. Then for all roles assigned to this authenticated principal it will + try to check and create them using identity modules. This behavior can be altered using following options: + <itemizedlist> + <listitem><para> + <emphasis role="bold">userModuleJNDIName</emphasis> - JNDI name of portal UserModule. This option is <emphasis>obligatory</emphasis> + if <emphasis>synchronizeIdentity</emphasis> option is set to <emphasis>true</emphasis></para> + </listitem> + <listitem><para> + <emphasis role="bold">roleModuleJNDIName</emphasis> - JNDI name of portal RoleModule. This option is <emphasis>obligatory</emphasis> + if <emphasis>synchronizeIdentity</emphasis> and <emphasis>synchronizeRoles</emphasis> options are set to <emphasis>true</emphasis></para> + </listitem> + <listitem><para> + <emphasis role="bold">membershipModuleJNDIName</emphasis> - JNDI name of portal MembershipModule. This option is <emphasis>obligatory</emphasis> + if <emphasis>synchronizeIdentity</emphasis> and <emphasis>synchronizeRoles</emphasis> options are set to <emphasis>true</emphasis></para> + </listitem> + <listitem><para> + <emphasis role="bold">userProfileModuleJNDIName</emphasis> - JNDI name of portal UserProfileModule. This option is <emphasis>obligatory</emphasis> + if <emphasis>synchronizeIdentity</emphasis> option is set to <emphasis>true</emphasis></para> + </listitem> + <listitem><para> + <emphasis role="bold">synchronizeIdentity</emphasis> - if set to <emphasis>true</emphasis> module will check if + successfully authenticated user exist in portal and if not it will try to create it. If user exists module will update its password + to the one that was just validated.</para> + </listitem> + <listitem><para> + <emphasis role="bold">synchronizeRoles</emphasis> - if set to <emphasis>true</emphasis> module will iterate over all roles assigned to + authenticated user and for each it will try to check if such role exists in portal and if not it will try to create it. This option is + checked only if <emphasis>synchronizeIdentity</emphasis> is set to true;</para> + </listitem> + <listitem><para> + <emphasis role="bold">additionalRole</emphasis> - module will add this role name to the group of principals assigned to the authenticated user.</para> + </listitem> + <listitem><para> + <emphasis role="bold">defaultAssignedRole</emphasis> - if <emphasis>synchronizeIdentity</emphasis> is set to true, module will try to assign + portal role with such name to the authenticated user. If such role doesn't exist in portal, module will try to create it. </para> + </listitem> + </itemizedlist> + For obvious reasons this is designed to use with portal identity modules configured with DB and not LDAP</para> + </section> + <section> + <title>org.jboss.portal.identity.auth.SynchronizingLdapExtLoginModule</title> + <para>All options that apply for <emphasis>SynchronizingLdapLoginModule</emphasis> also apply here. It's the same kind of wrapper + made around <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=LdapExtLoginModule&quo... from JBossSX. + Sample configuration can look like this:</para> + <programlisting><![CDATA[ + <login-module code="org.jboss.portal.identity.auth.SynchronizingLDAPExtLoginModule" + flag="required"> + <module-option name="synchronizeIdentity">true</module-option> + <module-option name="synchronizeRoles">true</module-option> + <module-option name="additionalRole">Authenticated</module-option> + <module-option name="defaultAssignedRole">User</module-option> + <module-option name="userModuleJNDIName">java:/portal/UserModule</module-option> + <module-option name="roleModuleJNDIName">java:/portal/RoleModule</module-option> + <module-option name="membershipModuleJNDIName">java:/portal/MembershipModule + </module-option> + <module-option name="userProfileModuleJNDIName">java:/portal/UserProfileModule + </module-option> + <module-option name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory + </module-option> + <module-option name="java.naming.provider.url">ldap://example.com:10389/ + </module-option> + <module-option name="java.naming.security.authentication">simple</module-option> + <module-option name="bindDN">cn=Directory Manager</module-option> + <module-option name="bindCredential">secret</module-option> + <module-option name="baseCtxDN">ou=People,dc=example,dc=com</module-option> + <module-option name="baseFilter">(uid={0})</module-option> + <module-option name="rolesCtxDN">ou=Roles,dc=example,dc=com</module-option> + <module-option name="roleFilter">(member={1})</module-option> + <module-option name="roleAttributeID">cn</module-option> + <module-option name="roleRecursion">-1</module-option> + <module-option name="searchTimeLimit">10000</module-option> + <module-option name="searchScope">SUBTREE_SCOPE</module-option> + <module-option name="allowEmptyPasswords">false</module-option> +</login-module>]]> + </programlisting> + </section> + <section id="authentication.synchronizing_login_module"> + <title>org.jboss.portal.identity.auth.SynchronizingLoginModule</title> + <para> + This module is designed to provide synchronization support for any other LoginModule placed in the authentication stack. + It leverages the fact that in JAAS authentication process occurs in two phases. In first phase when login() method is invoked + it always returns "true". Because of this behavior <emphasis>SynchronizingLoginModule</emphasis> should be always used with + "optional" flag. + More over it should be placed after the module we want to leverage as a source for synchronization and that module should have "required" flag set. + During the second phase when commit() method is invoked it gets user <emphasis>Subject</emphasis> and its <emphasis>Principal</emphasis>s + and tries to synchronize them into storage configured for portal identity modules. For this purposes such options are supported: + <itemizedlist> + <listitem><para> + <emphasis role="bold">userModuleJNDIName</emphasis> - JNDI name of portal UserModule. This option is <emphasis>obligatory</emphasis> + if <emphasis>synchronizeIdentity</emphasis> option is set to <emphasis>true</emphasis></para> + </listitem> + <listitem><para> + <emphasis role="bold">roleModuleJNDIName</emphasis> - JNDI name of portal RoleModule. This option is <emphasis>obligatory</emphasis> + if <emphasis>synchronizeIdentity</emphasis> and <emphasis>synchronizeRoles</emphasis> options are set to <emphasis>true</emphasis></para> + </listitem> + <listitem><para> + <emphasis role="bold">membershipModuleJNDIName</emphasis> - JNDI name of portal MembershipModule. This option is <emphasis>obligatory</emphasis> + if <emphasis>synchronizeIdentity</emphasis> and <emphasis>synchronizeRoles</emphasis> options are set to <emphasis>true</emphasis></para> + </listitem> + <listitem><para> + <emphasis role="bold">userProfileModuleJNDIName</emphasis> - JNDI name of portal UserProfileModule. This option is <emphasis>obligatory</emphasis> + if <emphasis>synchronizeIdentity</emphasis> option is set to <emphasis>true</emphasis></para> + </listitem> + <listitem><para> + <emphasis role="bold">synchronizeIdentity</emphasis> - if set to <emphasis>true</emphasis> module will check if + successfully authenticated user exist in portal and if not it will try to create it. If user exists module will update its password + to the one that was just validated.</para> + </listitem> + <listitem><para> + <emphasis role="bold">synchronizeRoles</emphasis> - if set to <emphasis>true</emphasis> module will iterate over all roles assigned to + authenticated user and for each it will try to check if such role exists in portal and if not it will try to create it. This option is + checked only if <emphasis>synchronizeIdentity</emphasis> is set to true;</para> + </listitem> + <listitem><para> + <emphasis role="bold">additionalRole</emphasis> - module will add this role name to the group of principals assigned to the authenticated user.</para> + </listitem> + <listitem><para> + <emphasis role="bold">defaultAssignedRole</emphasis> - if <emphasis>synchronizeIdentity</emphasis> is set to true, module will try to assign + portal role with such name to the authenticated user. If such role doesn't exist in portal, module will try to create it.</para> + </listitem> + </itemizedlist> + <note><title>Note</title><para>Example of usage in LDAP authentication can be found in <xref linkend="ldap.synchronizing"/>.</para></note> + </para> + </section> + </section> +</chapter> + <chapter id="ldap"> +<!-- <chapterinfo> + <author> + <firstname>Boleslaw</firstname> + <surname>Dawidowicz</surname> + </author> + </chapterinfo>--> + <title>LDAP</title> + <para>This chapter describes how to setup LDAP support in JBoss Portal</para> + <note><title>Note</title> + <para>To be able to fully understand this chapter you should also read <xref linkend="identity"/> and + <xref linkend="authentication"/> before. </para></note> + <section> + <title>How to enable LDAP usage in JBoss Portal</title> + <para>We'll describe here the simple steps that you will need to perform to enable LDAP support in JBoss Portal. + For additional information you need to read more about configuration of identity and specific implementations of identity modules</para> + <para>There are two ways to achieve this:</para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">jboss-portal.sar/META-INF/jboss-service.xml</emphasis> + in section: + </para> + <programlisting><![CDATA[ +<mbean + code="org.jboss.portal.identity.IdentityServiceControllerImpl" + name="portal:service=Module,type=IdentityServiceController" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <depends>portal:service=Hibernate</depends> + <attribute name="JndiName">java:/portal/IdentityServiceController</attribute> + <attribute name="RegisterMBeans">true</attribute> + <attribute name="ConfigFile">conf/identity/identity-config.xml</attribute> + <attribute name="DefaultConfigFile">conf/identity/standardidentity-config.xml</attribute> +</mbean>]]></programlisting> + <para> + change + <emphasis role="bold">identity-config.xml</emphasis> + to + <emphasis role="bold">ldap_identity-config.xml</emphasis> + </para> + </listitem> + <listitem> + <para>Swap the names or content of files in + <emphasis role="bold">jboss-portal.sar/conf/identity/identity-config.xml</emphasis> + and + <emphasis role="bold">jboss-portal.sar/conf/identity/ldap_identity-config.xml</emphasis> + + </para> + </listitem> + </itemizedlist> + <para> + After doing one of the above changes you need to edit configuration file that you choose to + use (identity-config.xml or ldap_identity-config.xml) and configure LDAP connection options in section: + </para> + <programlisting><![CDATA[ +<datasource> + <name>LDAP</name> + <config> + <option> + <name>host</name> + <value>jboss.com</value> + </option> + <option> + <name>port</name> + <value>10389</value> + </option> + <option> + <name>adminDN</name> + <value>cn=Directory Manager</value> + </option> + <option> + <name>adminPassword</name> + <value>qpq123qpq</value> + </option> + </config> +</datasource>]]></programlisting> + <para> + You also need to specify options for your LDAP tree (described in configuration documentation) like those: + </para> + <programlisting><![CDATA[ +<option-group> + <group-name>common</group-name> + <option> + <name>userCtxDN</name> + <value>ou=People,dc=portal26,dc=jboss,dc=com</value> + </option> + <option> + <name>roleCtxDN</name> + <value>ou=Roles,dc=portal26,dc=jboss,dc=com</value> + </option> +</option-group>]]></programlisting> + + <note><title>Note</title><para> + Under <emphasis role="bold">PORTAL_SOURCES/identity/src/resources/example/</emphasis> you can find a sample ldif that + you can use to populate LDAP server and quickly start playing with it.</para> + </note> + + </section> + <section> + <title>Configuration of LDAP connection</title> + <section> + <title>Connection Pooling</title> + <para>JBoss Portal uses <ulink url="http://java.sun.com/products/jndi/tutorial/ldap/connect/pool.ht... pooling</ulink> provided by <ulink url="http://java.sun.com/products/jndi/">JNDI</ulink>;, and is enabled by default. Use the following options to configure connection pooling settings:</para> + <programlisting><![CDATA[ +<datasource> + <name>LDAP</name> + <config> + ... + <!-- com.sun.jndi.ldap.connect.pool --> + <option> + <name>pooling</name> + <value>true</value> + </option> + + <!-- com.sun.jndi.ldap.connect.pool.protocol --> + <option> + <name>poolingProtocol</name> + <value>plain ssl</value> + </option> + + <!-- com.sun.jndi.ldap.connect.pool.timeout --> + <option> + <name>poolingTimeout</name> + <value>300000</value> + </option> + + <!-- com.sun.jndi.ldap.connect.pool.debug --> + <option> + <name>pooling</name> + <value> ... </value> + </option> + + <!-- com.sun.jndi.ldap.connect.pool.initsize --> + <option> + <name>poolingInitsize</name> + <value> ... </value> + </option> + + <!-- com.sun.jndi.ldap.connect.pool.maxsize --> + <option> + <name>poolingMaxsize</name> + <value> ... </value> + </option> + + <!-- com.sun.jndi.ldap.connect.pool.prefsize --> + <option> + <name>poolingPrefsize</name> + <value> ... </value> + </option> + + ... + </config> +</datasource>]]></programlisting> + <para> + Remember, as it is described in the <ulink url="http://java.sun.com/products/jndi/tutorial/ldap/connect/config.... documentation</ulink>, these options are system properties, not environment properties, and as such, they affect all connection pooling requests in the <trademark class="trade">Java runtime environment</trademark>. + </para> + + </section> + <section> + <title>SSL</title> + <para>The setup is very similar to the one described in LdapLoginModule <ulink url="http://www.jboss.org/wiki/Wiki.jsp?page=LdapLoginModule"&g... page</ulink></para> + <para>You need to modify your identity configuration file and add "protocol"</para> + <programlisting><![CDATA[ +<datasource> + <name>LDAP</name> + <config> + ... + <option> + <name>protocol</name> + <value>ssl</value> + </option> + ... + </config> +</datasource>]]></programlisting> + <para> + Then you need to have LDAP server certificate imported into your keystore. You can use following command: + <programlisting>keytool -import -file ldapcert.der -keystore ldap.truststore</programlisting> + </para> + <para> + Now you need to change the settings to use the alternative truststore. That can be done in the properties-service.xml in deploy directory: + <programlisting><![CDATA[ +<attribute name="Properties"> + javax.net.ssl.trustStore=../some/path/to/ldap.truststore + javax.net.ssl.trustStorePassword=somepw +</attribute>]]></programlisting> + </para> + </section> + <section> + <title>ExternalContext</title> + <para>Instead of configuring your own connection you can use JNDI context federation mechanism in JBoss Application Server. Configuration of + ExternalContext is described in <ulink url="http://docs.jboss.com/jbossas/guides/j2eeguide/r2/en/html_singl... Application Server documentation</ulink></para> + <para>When you have ExternalContext configured you can use it in JBoss Portal by providing proper JNDI name in the configuration: + <programlisting><![CDATA[ +<datasource> + <name>LDAP</name> + <config> + <option> + <name>externalContextJndiName</name> + <value>external/ldap/jboss</value> + </option> + </config> +</datasource>]]></programlisting> +<note><title>Note</title><para>When using "externalContextJndiName" you don't need to specify any other option for this datasource</para></note> + </para> + </section> + </section> + <section id="ldap.ldap_identity_modules"> + <title>LDAP Identity Modules</title> + <para>JBoss Portal comes with base LDAP implementation of all identity modules.</para> + <section> + <title>Common settings</title> + <para>For all modules you can set two config options: + <itemizedlist> + <listitem><para> + <emphasis role="bold">jNDIName</emphasis> - JNDI name under which this module will be registered</para> + </listitem> + <listitem> + <para><emphasis role="bold">connectionJNDIName</emphasis> - JNDI name under which LDAP datasource is registered </para> + </listitem> + </itemizedlist> + <note><title>Note</title><para>Most configuration of LDAP identity modules is done in <emphasis>options</emphasis> section by adding module specific options + in <emphasis>"common"</emphasis> option-group or in other module specific groups.</para></note> + </para> + </section> + <section> + <title>UserModule</title> + <para> + <table frame="all"> + <title>Comparision of UserModule implementations</title> + <tgroup cols="3" align="left" colsep="1"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <colspec colname="c3"/> + <thead> + <row> + <entry align="center" morerows="1">Features</entry> + <entry align="center" namest="c2" nameend="c3">UserModule</entry> + </row> + <row> + <entry align="center">LDAPUserModuleImpl</entry> + <entry align="center">LDAPExtUserModuleImpl</entry> + </row> + </thead> + <tbody> + <row> + <entry>User creation</entry> + <entry align="center">X</entry> + <entry align="center">-</entry> + </row> + <row> + <entry>User removal</entry> + <entry align="center">X</entry> + <entry align="center">-</entry> + </row> + <row> + <entry>User search</entry> + <entry align="center">Flat - one level scope</entry> + <entry align="center">Flexible filter - sub tree scope</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <section> + <title>LDAPUserModuleImpl</title> + <para>This is the base implementation of LDAP <emphasis>UserModule</emphasis>. It supports user creation, but will retrieve users and create them + in strictly specified place in LDAP tree.</para> + <para>To enable it in your configuration you should have: + <programlisting><![CDATA[ +<module> + <!--type used to correctly map in IdentityContext registry--> + <type>User</type> + <implementation>LDAP</implementation> + <config/> +</module>]]></programlisting> + </para> + <para>org.jboss.portal.identity.ldap.LDAPUserModuleImpl configuration option-groups options: + </para> + <itemizedlist> + <listitem><para> + <emphasis role="bold">common</emphasis>: + <itemizedlist> + <listitem><para> + <emphasis role="bold">userCtxDN</emphasis> - DN that will be used as context for user searches</para> + </listitem> + <listitem> + <para> <emphasis role="bold">uidAttributeID</emphasis> - attribute name under which user name is specified. Default value is "uid"</para> + </listitem> + <listitem> + <para> <emphasis role="bold">passwordAttributeID</emphasis> - attribute name under which user password is specified. Default value is "userPassword"</para> + </listitem> + <listitem> + <para><emphasis role="bold">principalDNPrefix</emphasis> and <emphasis role="bold">principalDNSuffix</emphasis></para> + </listitem> + <listitem> + <para><emphasis role="bold">searchTimeLimit</emphasis> - The timeout in milliseconds for the user searches. Defaults to 10000 (10 seconds).</para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> <emphasis role="bold">userCreateAttibutes</emphasis>: This option-group defines a set of ldap attributes that will be set on user entry creation. + Option name will be used as attribute name, and option values as attribute values. This enables to fulfill LDAP schema requirements.</para> + </listitem> + </itemizedlist> + + <para> Example configuration: + <programlisting> + <![CDATA[ +<option-group> + <group-name>common</group-name> + <option> + <name>userCtxDN</name> + <value>ou=People,o=portal,dc=my-domain,dc=com</value> + </option> + <option> + <name>uidAttributeID</name> + <value>uid</value> + </option> + <option> + <name>passwordAttributeID</name> + <value>userPassword</value> + </option> +</option-group> +<option-group> + <group-name>userCreateAttibutes</group-name> + <option> + <name>objectClass</name> + <!--This objectclasses should work with Red Hat Directory--> + <value>top</value> + <value>person</value> + <value>inetOrgPerson</value> + </option> + <!--Schema requires those to have initial value--> + <option> + <name>cn</name> + <value>none</value> + </option> + <option> + <name>sn</name> + <value>none</value> + </option> +</option-group>]]></programlisting> + + </para> + </section> + <section> + <title>LDAPExtUserModuleImpl</title> + <para>Aim of this implementation is to give more flexibility for users retrieval. You can specify LDAP filter + that will be used for searches. This module doesn't support user creation and removal</para> + <para>To enable it in your configuration you should have: + <programlisting><![CDATA[ +<module> + <!--type used to correctly map in IdentityContext registry--> + <type>User</type> + <implementation>LDAP</implementation> + <class>org.jboss.portal.identity.ldap.LDAPExtUserModuleImpl</class> + <config/> +</module]]> + </programlisting> + </para> + <para>org.jboss.portal.identity.ldap.LDAPExtUserModuleImpl configuration option-groups options: + <itemizedlist> + <listitem><para> + <emphasis role="bold">common</emphasis>: + <itemizedlist> + <listitem> + <para> <emphasis role="bold">userCtxDN</emphasis> - DN that will be used as context for user searches. More than one value can be specified.</para> + </listitem> + <listitem> + <para> <emphasis role="bold">userSearchFilter</emphasis> - ldap filter to search users with. {0} will be substitute with user name. Example filter can look like this: + "(uid={0})". This substituion behavior comes from the standard <emphasis>DirContext.search(Name, String, Object, SearchControls cons)</emphasis> method</para> + </listitem> + <listitem> + <para><emphasis role="bold">uidAttributeID</emphasis> - attribute name under which user name is specified. Default value is "uid"</para> + </listitem> + <listitem> + <para> <emphasis role="bold">searchTimeLimit</emphasis> - The timeout in milliseconds for the user searches. Defaults to 10000 (10 seconds).</para> + </listitem> + <!--<listitem> + <emphasis role="bold">searchScope</emphasis> - Sets the search scope to one of the strings. The default is SUBTREE_SCOPE. + <itemizedlist> + <listitem> + <emphasis role="bold">OBJECT_SCOPE</emphasis> - only search the named users context. + </listitem> + <listitem> + <emphasis role="bold">ONELEVEL_SCOPE</emphasis> - search directly under the named users context. + </listitem> + <listitem> + <emphasis role="bold">SUBTREE_SCOPE</emphasis> - If the users context is not a <emphasis>DirContext</emphasis>, search only the object. + If the users context is a <emphasis>DirContext</emphasis>, search the subtree rooted at the named object, including the named object itself. + </listitem> + </itemizedlist> + </listitem>--> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + + </para> + </section> + </section> + <section> + <title>RoleModule</title> + <para> + <table frame="all"> + <title>Comparision of RoleModule implementations</title> + <tgroup cols="3"> + + <thead> + <row> + <entry align="center">Features</entry> + <entry align="center">RoleModule</entry> + </row> + <row> + <entry align="center">LDAPRoleModuleImpl</entry> + <entry align="center">LDAPExtRoleModuleImpl</entry> + </row> + </thead> + <tbody> + <row> + <entry>Role creation</entry> + <entry align="center">X</entry> + <entry align="center">-</entry> + </row> + <row> + <entry>Role removal</entry> + <entry align="center">X</entry> + <entry align="center">-</entry> + </row> + <row> + <entry>Role search</entry> + <entry align="center">Flat - one level scope</entry> + <entry align="center">Flexible filter - sub tree scope</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <section> + <title>LDAPRoleModuleImpl</title> + <para>This is the base implementation of LDAP <emphasis>RoleModule</emphasis>. It supports user creation, but will retrieve roles and create them + in strictly specified place in LDAP tree.</para> + <para>To enable it in your configuration you should have: + <programlisting><![CDATA[ +<module> + <!--type used to correctly map in IdentityContext registry--> + <type>Role</type> + <implementation>LDAP</implementation> + <config/> +</module>]]> + </programlisting> + </para> + <para>org.jboss.portal.identity.ldap.LDAPRoleModuleImpl configuration option-groups options: + <itemizedlist> + <listitem><para> + <emphasis role="bold">common</emphasis>: + <itemizedlist> + <listitem> + <para><emphasis role="bold">roleCtxDN</emphasis> - DN that will be used as context for role searches.</para> + </listitem> + <listitem> + <para> <emphasis role="bold">ridAttributeID</emphasis> - attribute name under which role name is specified. Default value is "cn".</para> + </listitem> + <listitem> + <para><emphasis role="bold">roleDisplayNameAttributeID</emphasis> - attribute name under which role display name is specified. Default value is "cn".</para> + </listitem> + <listitem> + <para> <emphasis role="bold">searchTimeLimit</emphasis> - The timeout in milliseconds for the roles searches. Defaults to 10000 (10 seconds).</para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </para> + </section> + <section> + <title>LDAPExtRoleModuleImpl</title> + <para>Aim of this implementation is to give more flexibility for roles retrieval. You can specify LDAP filter + that will be used for searches. This module doesn't support role creation and removal.</para> + <para>This module doesn't support role creation and removal</para> + <para>To enable it in your configuration you should have:</para> + <programlisting><![CDATA[ +<module> + <!--type used to correctly map in IdentityContext registry--> + <type>Role</type> + <implementation>LDAP</implementation> + <class>org.jboss.portal.identity.ldap.LDAPExtRoleModuleImpl</class> + <config/> +</module>]]> + </programlisting> + + <para>org.jboss.portal.identity.ldap.LDAPExtRoleModuleImpl configuration option-groups options: + </para> + <itemizedlist> + <listitem> + <para> <emphasis role="bold">common</emphasis>: + <itemizedlist> + <listitem> + <para> <emphasis role="bold">roleCtxDN</emphasis> - DN that will be used as context for role searches. More than one value can be specified.</para> + </listitem> + <listitem> + <para><emphasis role="bold">roleSearchFilter</emphasis> - ldap filter to search roles with. {0} will be substitute with role name. Example filter can look like this: + "(cn={0})". This substituion behavior comes from the standard <emphasis>DirContext.search(Name, String, Object, SearchControls cons)</emphasis> method.</para> + </listitem> + <listitem> + <para> <emphasis role="bold">ridAttributeID</emphasis> - attribute name under which role name is specified. Default value is "cn".</para> + </listitem> + <listitem> + <para> <emphasis role="bold">roleDisplayNameAttributeID</emphasis> - attribute name under which role display name is specified. Default value is "cn".</para> + </listitem> + <listitem> + <para> <emphasis role="bold">searchTimeLimit</emphasis> - The timeout in milliseconds for the roles searches. Defaults to 10000 (10 seconds).</para> + </listitem> + <listitem> + <para><emphasis role="bold">searchScope</emphasis> - Sets the search scope to one of the strings. The default is SUBTREE_SCOPE. + <itemizedlist> + <listitem> + <para><emphasis role="bold">OBJECT_SCOPE</emphasis> - only search the named roles context.</para> + </listitem> + <listitem> + <para><emphasis role="bold">ONELEVEL_SCOPE</emphasis> - search directly under the named roles context.</para> + </listitem> + <listitem> + <para> <emphasis role="bold">SUBTREE_SCOPE</emphasis> - If the roles context is not a <emphasis>DirContext</emphasis>, search only the object. + If the roles context is a <emphasis>DirContext</emphasis>, search the subtree rooted at the named object, including the named object itself.</para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + + + <note><title>Note</title><para>In <emphasis>UserModule</emphasis> there are two methods that handle offset/limit (pagination) behavior. + <programlisting> + <![CDATA[ +/** Get a range of users.*/ +Set findUsers(int offset, int limit) throws IdentityException, IllegalArgumentException; + +/** Get a range of users.*/ +Set findUsersFilteredByUserName(String filter, int offset, int limit) + throws IdentityException, IllegalArgumentException; + ]]> + </programlisting> + Pagination support is not widely implemented in LDAP servers. Because <emphasis>UserModule</emphasis> + implementations rely on JNDI and are targetted to be LDAP server agnostic those methods aren't very effecient. + As long as you don't rely on portal user management and use dedicated tools for user provisioning it + shouldn't bother you. Otherwise you should consider extending the implementation and providing + solution dedicated to your LDAP server.</para> + </note> + </section> + </section> + <section> + <title>MembershipModule</title> + <para> + <table frame="all"> + <title>Comparision of MembershipModule implementations</title> + <tgroup cols="3" align="left"> + + <thead> + <row> + <entry align="center">Features</entry> + <entry align="center">MembershipModule</entry> + </row> + <row> + <entry align="center">LDAPStaticGroupMembershipModuleImpl</entry> + <entry align="center">LDAPStaticRoleMembershipModuleImpl</entry> + </row> + </thead> + <tbody> + <row> + <entry>Role assignment stored in LDAP role entry</entry> + <entry align="center">X</entry> + <entry align="center">-</entry> + </row> + <row> + <entry>Role assignment stored in LDAP user entry</entry> + <entry align="center">-</entry> + <entry align="center">X</entry> + </row> + <row> + <entry>User/Role relationship creation</entry> + <entry align="center">X</entry> + <entry align="center">X</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <section> + <title>LDAPStaticGroupMembershipModuleImpl</title> + <para>This module support tree shape where role entries keep information about users that are their members.</para> + <para>To enable it in your configuration you should have: + <programlisting><![CDATA[ +<module> + <!--type used to correctly map in IdentityContext registry--> + <type>Membership</type> + <implementation>LDAP</implementation> + <config/> +</module>]]> + </programlisting> + </para> + <para>org.jboss.portal.identity.ldap.LDAPStaticGroupMembershipModuleImpl configuration option-groups options: + <itemizedlist> + <listitem><para> + <emphasis role="bold">common</emphasis>: + <itemizedlist> + <listitem> + <para> <emphasis role="bold">membershipAttributeID</emphasis> - LDAP attribute that defines member users ids. This will be used to retrieved users from role entry.</para> + </listitem> + <listitem> + <para> <emphasis role="bold">membershipAttributeIsDN</emphasis> - defines if values of attribute defined in <emphasis>membershipAttributeID</emphasis> are fully qualified + LDAP DNs.</para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </para> + </section> + <section> + <title>LDAPStaticRoleMembershipModuleImpl</title> + <para>This module support tree shape where user entries keep information about roles that they belong to.</para> + <para>To enable it in your configuration you should have: + <programlisting><![CDATA[ +<module> + <!--type used to correctly map in IdentityContext registry--> + <type>Membership</type> + <implementation>LDAP</implementation> + <class>org.jboss.portal.identity.ldap.LDAPStaticRoleMembershipModuleImpl</class> + <config/> +</module>]]> + </programlisting> + </para> + <para>org.jboss.portal.identity.ldap.LDAPStaticRoleMembershipModuleImpl configuration option-groups options: + <itemizedlist> + <listitem><para> + <emphasis role="bold">common</emphasis>: + <itemizedlist> + <listitem><para> + <emphasis role="bold">membershipAttributeID</emphasis> - LDAP attribute that defines role ids that user belongs to. This will be used to retrieved roles + from user entry.</para> + </listitem> + <listitem> + <para> <emphasis role="bold">membershipAttributeIsDN</emphasis> - defines if values of attribute defined in <emphasis>membershipAttributeID</emphasis> are fully qualified + LDAP DNs.</para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </para> + </section> + </section> + <section> + <title>UserProfileModule</title> + <section> + <title>LDAPUserProfileModuleImpl</title> + <para>This is standard implementation that enables to retrieve user properties from atributes in LDAP entries.</para> + <para>To enable it in your configuration you should have: + <programlisting><![CDATA[ +<module> + <type>UserProfile</type> + <implementation>DELEGATING</implementation> + <config> + <option> + <name>ldapModuleJNDIName</name> + <value>java:/portal/LDAPUserProfileModule</value> + </option> + </config> +</module> +<module> + <type>DBDelegateUserProfile</type> + <implementation>DB</implementation> + <config> + <option> + <name>randomSynchronizePassword</name> + <value>true</value> + </option> + </config> +</module> +<module> + <type>LDAPDelegateUserProfile</type> + <implementation>LDAP</implementation> + <config/> +</module>]]> + </programlisting> + <note><title>Note</title><para>Using such configuration you will have LDAP MembershipModule along with DB MembershipModule and Delegating MembershipModule. Please read + <xref linkend="identity.management_api"/> to see why this is important.</para> + </note> + </para> + <para>org.jboss.portal.identity.ldap.LDAPUserModuleImpl configuration option-groups options: + <itemizedlist> + <listitem> + <para><emphasis role="bold">common</emphasis>: + <itemizedlist> + <listitem> + <para> <emphasis role="bold">profileConfigFile</emphasis> - file with user profile configuration. If this option is not set, and we use delegating UserProfileModule, + profile configuration will be obtained from it.</para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </para> + </section> + </section> + </section> + <section> + <title>LDAP server tree shapes</title> + <para>JBoss Portal supports full user/role management for simple LDAP tree shapes. Some more flexible + trees can be supported by <emphasis>LdapExtUserModuleImpl</emphasis> and <emphasis>LdapExtRoleModuleImpl</emphasis> + - but without user/role creation and removal capabilities. + However if you have complex LDAP tree you should consider using + <xref linkend="authentication.synchronizing_login_module"/> described in + <xref linkend="authentication"/> along with dedicated tools for user + provisioning provided with LDAP server.</para> + <para> + In following subsections we will describe two base LDAP tree shapes along with example LDIFs and portal + identity modules configurations. Those two examples differ only by using different <emphasis>MembershipModule</emphasis> + implementations and describe only tree shapes with supported user/role creation and removal capabilities. + </para> + <section> + <title>Keeping users membership in role entries</title> + <para>In this example, information about users/roles assignment is stored in roles entries using LDAP + "<emphasis>member</emphasis>". Of course any other attribute that comes with schema can be used for this.</para> + <para>Example tree shape in LDAP browser + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/ldap/tree1-1.png" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + <para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/ldap/tree1-2.png" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + <section> + <title>Example LDIF</title> + <para> + <programlisting><![CDATA[ +dn: dc=example,dc=com +objectclass: top +objectclass: dcObject +objectclass: organization +dc: example +o: example + +dn: ou=People,dc=example,dc=com +objectclass: top +objectclass: organizationalUnit +ou: People + +dn: uid=user,ou=People,dc=example,dc=com +objectclass: top +objectclass: inetOrgPerson +objectclass: person +uid: user +cn: JBoss Portal user +sn: user +userPassword: user +mail: email(a)email.com + +dn: uid=admin,ou=People,dc=example,dc=com +objectclass: top +objectclass: inetOrgPerson +objectclass: person +uid: admin +cn: JBoss Portal admin +sn: admin +userPassword: admin +mail: email(a)email.com + +dn: ou=Roles,dc=example,dc=com +objectclass: top +objectclass: organizationalUnit +ou: Roles + +dn: cn=User,ou=Roles,dc=example,dc=com +objectClass: top +objectClass: groupOfNames +cn: User +description: the JBoss Portal user group +member: uid=user,ou=People,dc=example,dc=com + +dn: cn=Admin,ou=Roles,dc=example,dc=com +objectClass: top +objectClass: groupOfNames +cn: Echo +description: the JBoss Portal admin group +member: uid=admin,ou=People,dc=example,dc=com]]></programlisting> + </para> + </section> + <section> + <title>Example identity configuration</title> + <para> + <programlisting><![CDATA[ + <modules> + <module> + <!--type used to correctly map in IdentityContext registry--> + <type>User</type> + <implementation>LDAP</implementation> + <config/> + </module> + <module> + <type>Role</type> + <implementation>LDAP</implementation> + <config/> + </module> + <module> + <type>Membership</type> + <implementation>LDAP</implementation> + <config/> + </module> + <module> + <type>UserProfile</type> + <implementation>DELEGATING</implementation> + <config> + <option> + <name>ldapModuleJNDIName</name> + <value>java:/portal/LDAPUserProfileModule</value> + </option> + </config> + </module> + <module> + <type>DBDelegateUserProfile</type> + <implementation>DB</implementation> + <config> + <option> + <name>randomSynchronizePassword</name> + <value>true</value> + </option> + </config> + </module> + <module> + <type>LDAPDelegateUserProfile</type> + <implementation>LDAP</implementation> + <config/> + </module> +</modules> + +<options> + <option-group> + <group-name>common</group-name> + <option> + <name>userCtxDN</name> + <value>ou=People,dc=example,dc=com</value> + </option> + <option> + <name>roleCtxDN</name> + <value>ou=Roles,dc=example,dc=com</value> + </option> + </option-group> + <option-group> + <group-name>userCreateAttibutes</group-name> + <option> + <name>objectClass</name> + <!--This objectclasses should work with Red Hat Directory--> + <value>top</value> + <value>person</value> + <value>inetOrgPerson</value> + </option> + <!--Schema requires those to have initial value--> + <option> + <name>cn</name> + <value>none</value> + </option> + <option> + <name>sn</name> + <value>none</value> + </option> + </option-group> + <option-group> + <group-name>roleCreateAttibutes</group-name> + <!--Schema requires those to have initial value--> + <option> + <name>cn</name> + <value>none</value> + </option> + <!--Some directory servers require this attribute to be valid DN--> + <!--For safety reasons point to the admin user here--> + <option> + <name>member</name> + <value>uid=admin,ou=People,dc=example,dc=com</value> + </option> + </option-group> +</options>]]></programlisting> + </para> + </section> + + </section> + <section> + <title>Keeping users membership in user entries</title> + <para>In this example, information about users/roles assignment is stored in user entries using LDAP + "<emphasis>memberOf</emphasis>". Of course any other attribute that comes with schema can be used for this.</para> + <para>Example tree shape in LDAP browser + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/ldap/tree2-3.png" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + <para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/ldap/tree2-4.png" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + <section> + <title>Example LDIF</title> + <para> + <programlisting><![CDATA[ +dn: dc=example,dc=com +objectclass: top +objectclass: dcObject +objectclass: organization +dc: example +o: example + +dn: o=example2,dc=example,dc=com +objectclass: top +objectclass: organization +o: example2 + +dn: ou=People,o=example2,dc=example,dc=com +objectclass: top +objectclass: organizationalUnit +ou: People + +dn: uid=admin,ou=People,o=example2,dc=example,dc=com +objectclass: top +objectclass: inetOrgPerson +objectclass: inetUser +uid: admin +cn: JBoss Portal admin +sn: admin +userPassword: admin +mail: email(a)email.com +memberOf: cn=Admin,ou=Roles,o=example2,dc=example,dc=com + +dn: uid=user,ou=People,o=example2,dc=example,dc=com +objectclass: top +objectclass: inetOrgPerson +objectclass: inetUser +uid: user +cn: JBoss Portal user +sn: user +userPassword: user +mail: email(a)email.com +memberOf: cn=User,ou=Roles,o=example2,dc=example,dc=com + +dn: ou=Roles,o=example2,dc=example,dc=com +objectclass: top +objectclass: organizationalUnit +ou: Roles + +dn: cn=User,ou=Roles,o=example2,dc=example,dc=com +objectClass: top +objectClass: organizationalRole +cn: User +description: the JBoss Portal user group + +dn: cn=Admin,ou=Roles,o=example2,dc=example,dc=com +objectClass: top +objectClass: organizationalRole +cn: Echo +description: the JBoss Portal admin group]]></programlisting> + </para> + </section> + <section> + <title>Example identity configuration</title> + <para> + <programlisting><![CDATA[ + <modules> + <module> + <!--type used to correctly map in IdentityContext registry--> + <type>User</type> + <implementation>LDAP</implementation> + <config/> + </module> + <module> + <type>Role</type> + <implementation>LDAP</implementation> + <config/> + </module> + <module> + <type>Membership</type> + <implementation>LDAP</implementation> + <class>org.jboss.portal.identity.ldap.LDAPStaticRoleMembershipModuleImpl</class> + <config/> + </module> + <module> + <type>UserProfile</type> + <implementation>DELEGATING</implementation> + <config> + <option> + <name>ldapModuleJNDIName</name> + <value>java:/portal/LDAPUserProfileModule</value> + </option> + </config> + </module> + <module> + <type>DBDelegateUserProfile</type> + <implementation>DB</implementation> + <config> + <option> + <name>randomSynchronizePassword</name> + <value>true</value> + </option> + </config> + </module> + <module> + <type>LDAPDelegateUserProfile</type> + <implementation>LDAP</implementation> + <config/> + </module> +</modules> + +<options> + <option-group> + <group-name>common</group-name> + <option> + <name>userCtxDN</name> + <value>ou=People,dc=example,dc=com</value> + </option> + <option> + <name>roleCtxDN</name> + <value>ou=Roles,dc=example,dc=com</value> + </option> + <option> + <name>membershipAttributeID</name> + <value>memberOf</value> + </option> + </option-group> + <option-group> + <group-name>userCreateAttibutes</group-name> + <option> + <name>objectClass</name> + <!--This objectclasses should work with Red Hat Directory--> + <value>top</value> + <value>person</value> + <value>inetOrgPerson</value> + </option> + <!--Schema requires those to have initial value--> + <option> + <name>cn</name> + <value>none</value> + </option> + <option> + <name>sn</name> + <value>none</value> + </option> + </option-group> + <option-group> + <group-name>roleCreateAttibutes</group-name> + <!--Schema requires those to have initial value--> + <option> + <name>cn</name> + <value>none</value> + </option> + <!--Some directory servers require this attribute to be valid DN--> + <!--For safety reasons point to the admin user here--> + <option> + <name>member</name> + <value>uid=admin,ou=People,dc=example,dc=com</value> + </option> + </option-group> +</options>]]></programlisting> + </para> + </section> + </section> + </section> + <section id="ldap.synchronizing"> + <title>Synchronizing LDAP configuration</title> + <para> + Like it was described in previous section, you can meet some limitations in identity modules support for more + complex LDAP tree shapes. To workaround this you can use identity synchronization on JAAS level. JBoss Portal comes with + <xref linkend="authentication.synchronizing_login_module"/> that can be easily + configured with other authentication solutions that support JAAS framework. Here we want to provide a simple + example on how it can be integrated with + <emphasis><ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=LdapExtLoginModule&quo... + from <emphasis>JBossSX</emphasis> framework.</emphasis> + </para> + <para> + First of all portal identity modules should be configured to work with portal database - default configuration. + This is important as we will leverage them, and we want to synchronize users identity into default portal storage + mechanism. So lets look at simple configuration that should take place in + <emphasis>jboss-portal.sar/conf/login-config.xml</emphasis> + <programlisting><![CDATA[ +<policy> + <!-- For the JCR CMS --> + <application-policy name="cms"> + <authentication> + <login-module code="org.apache.jackrabbit.core.security.SimpleLoginModule" + flag="required"/> + </authentication> + </application-policy> + + <application-policy name="portal"> + <authentication> + + <login-module code="org.jboss.security.auth.spi.LdapExtLoginModule" flag="required"> + <module-option name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory + </module-option> + <module-option name="java.naming.provider.url">ldap://example.com:10389/ + </module-option> + <module-option name="java.naming.security.authentication">simple</module-option> + <module-option name="bindDN">cn=Directory Manager</module-option> + <module-option name="bindCredential">lolo</module-option> + <module-option name="baseCtxDN">ou=People,dc=example,dc=com</module-option> + <module-option name="baseFilter">(uid={0})</module-option> + <module-option name="rolesCtxDN">ou=Roles,dc=example,dc=com</module-option> + <module-option name="roleFilter">(member={1})</module-option> + <module-option name="roleAttributeID">cn</module-option> + <module-option name="roleRecursion">-1</module-option> + <module-option name="searchTimeLimit">10000</module-option> + <module-option name="searchScope">SUBTREE_SCOPE</module-option> + <module-option name="allowEmptyPasswords">false</module-option> + </login-module> + + <login-module code="org.jboss.portal.identity.auth.SynchronizingLoginModule" + flag="optional"> + <module-option name="synchronizeIdentity">true</module-option> + <module-option name="synchronizeRoles">true</module-option> + <module-option name="additionalRole">Authenticated</module-option> + <module-option name="defaultAssignedRole">User</module-option> + <module-option name="userModuleJNDIName">java:/portal/UserModule</module-option> + <module-option name="roleModuleJNDIName">java:/portal/RoleModule</module-option> + <module-option name="membershipModuleJNDIName">java:/portal/MembershipModule + </module-option> + <module-option name="userProfileModuleJNDIName">java:/portal/UserProfileModule + </module-option> + </login-module> + + </authentication> + </application-policy> +</policy>]]></programlisting> + </para> + <para> + Few things are important in this configuration: + <itemizedlist> + <listitem><para><emphasis>LdapExtLoginModule</emphasis> has <emphasis>flag="required"</emphasis> set + which means that if this single <emphasis>LoginModule</emphasis> return <emphasis>fail</emphasis> + from authentication request whole process will fail. <emphasis>SynchronizingLoginModule</emphasis> + has <emphasis>flag="optional"</emphasis>. Such combination is critical as + <emphasis>SynchronizingLoginModule</emphasis> always authenticates user sucessfully no matter what + credentials were provided. You always must have at least one <emphasis>LoginModule</emphasis> that you + will rely on.</para> + </listitem> + <listitem> + <para><emphasis>SynchronizingLoginModule</emphasis> is always the <emphasis>last</emphasis> one in whole + authentication chain. This is because in <emphasis>commit</emphasis> phase it will take users + <emphasis>Subject</emphasis> and its <emphasis>Principals</emphasis> (roles) assigned by previous + <emphasis>LoginModule</emphasis>s and try to synchronize them. Roles assigned to authenticated user by + <emphasis>LoginModule</emphasis>s after it won't be handled.</para> + </listitem> + </itemizedlist> + </para> + </section> + <section> + <title>Supported LDAP servers</title> + <para>LDAP servers support depends on few conditions. In most cases they differ in schema support - various objectClass + objects are not present by default in server schema. Sometimes it can be workarounded by manually + extending schema.</para> + <para> + Servers can be + <itemizedlist> + <listitem><para><emphasis>Supported</emphasis></para></listitem> + <listitem><para><emphasis>Not Supported</emphasis></para></listitem> + <listitem><para><emphasis>Experimental</emphasis> - implementation can work with such server but it's not well tested so shouldn't be considered for production.</para></listitem> + </itemizedlist> + </para> + <table frame="all"> + <title>Support of identity modules with different LDAP servers</title> + <tgroup cols="8" align="left" colsep="1"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <colspec colname="c3"/> + <colspec colname="c4"/> + <colspec colname="c5"/> + <colspec colname="c6"/> + <colspec colname="c7"/> + <colspec colname="c8"/> + <thead> + <row> + <entry align="center" morerows="1">LDAP Server</entry> + <entry align="center" namest="c2" nameend="c3">UserModule</entry> + <entry align="center" namest="c4" nameend="c5">RoleModule</entry> + <entry align="center" namest="c6" nameend="c7">MembershipModule</entry> + <entry align="center">UserProfileModule</entry> + </row> + <row> + <entry>LDAPUserModuleImpl</entry> + <entry>LDAPExtUserModuleImpl</entry> + <entry>LDAPRoleModuleImpl</entry> + <entry>LDAPExtRoleModuleImpl</entry> + <entry>LDAPStaticGroupMembershipModuleImpl</entry> + <entry>LDAPStaticRoleMembershipModuleImpl</entry> + <entry>LDAPUserProfileModuleImpl</entry> + </row> + </thead> + <tbody> + <row> + <entry>Red Hat Directory Server</entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + </row> + <row> + <entry>OpenDS</entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + <entry align="center"><emphasis>Not Supported</emphasis></entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + </row> + <row> + <entry>OpenLDAP</entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + <entry align="center"><emphasis>Not Supported</emphasis></entry> + <entry align="center"><emphasis>Supported</emphasis></entry> + </row> + </tbody> + </tgroup> + </table> + </section> +</chapter> + <chapter id="sso"> +<!-- <chapterinfo> + <author> + <firstname>Boleslaw</firstname> + <surname>Dawidowicz</surname> + </author> + <author> + <firstname>Sohil</firstname> + <surname>Shah</surname> + </author> + </chapterinfo>--> + <title>Single Sign On</title> + <para>This chapter describes how to setup SSO in JBoss Portal</para> + <section> + <title>Overview of SSO in portal</title> + <para>Portal as an integration and aggregation platform provides some form of SSO by itself. When you log into + the portal you gain access to many systems through portlets using a single identity. Still in many cases you + need to integrate the portal infrastructure with other SSO enabled systems. There are many different Identity Management + solutions on the market. In most cases each SSO framework provides its own way to plug into Java EE application. For custom configurations + you need to have a good understanding of <xref linkend="identity"/> and <xref linkend="authentication"/> authentication mechanisms.</para> + </section> + + <section> + <title>Using an Apache Tomcat Valve</title> + <para>JBoss Application Server embeds Apache Tomcat as the default servlet container. Tomcat provides a builtin SSO support + using a valve. The Single Sign On Valve caches credentials on the server side, and then invisibly authenticate users when they + reach different web applications. Credentials are stored in a host-wide session which means that SSO will be effective throughout the session. + </para> + <section> + <title>Enabling the Apache Tomcat SSO Valve</title> + <para> + To enable SSO valve in Apache Tomcat you should uncomment the following line + <programlisting><![CDATA[<Valve className=’org.apache.catalina.authenticator.SingleSignOn’/>]]></programlisting> + in the <literal>$JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xml</literal> file. + More information can be found <ulink url="http://www.jboss.org/wiki/Wiki.jsp?page=SingleSignOn">h...;. + </para> + </section> + <section> + <title>Example of usage</title> + <para> + Lets look a little bit closer and configure SSO between portal and other web application. As an example + we'll use <emphasis>jmx-console</emphasis> web-app that comes with every JBoss Application Server installation. + You can find more information on how to secure <emphasis>jmx-console</emphasis> in <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=SecureTheJmxConsole&qu... AS wiki</ulink>. + </para> + <orderedlist> + <listitem> + <para>Take a clean install of <emphasis>JBoss Application Server</emphasis></para> + </listitem> + <listitem> + <para>Edit <emphasis>$JBOSS_HOME/server/default/deploy/jmx-console.war/WEB-INF/web.xml</emphasis> file and make sure it contains following content:</para> + <programlisting> + <![CDATA[ +<security-constraint> + <web-resource-collection> + <web-resource-name>HtmlAdaptor</web-resource-name> + <description>An example security config that only allows users with the + role JBossAdmin to access the HTML JMX console web application + </description> + <url-pattern>/*</url-pattern> + <http-method>GET</http-method> + <http-method>POST</http-method> + </web-resource-collection> + <auth-constraint> + <role-name>Admin</role-name> + </auth-constraint> +</security-constraint> + +<security-constraint> + <web-resource-collection> + <web-resource-name>Public</web-resource-name> + <url-pattern>/public/*</url-pattern> + <http-method>GET</http-method> + <http-method>POST</http-method> + </web-resource-collection> +</security-constraint> + +<login-config> + <auth-method>BASIC</auth-method> + <realm-name>jmx-console</realm-name> +</login-config> + +<security-role> + <role-name>Admin</role-name> +</security-role>]]> + </programlisting> + <para>This will secure <emphasis>jmx-console</emphasis> web application using BASIC browser authentication and restrict access for + users with <emphasis>Admin</emphasis> role only.</para> + </listitem> + <listitem> + <para> + Edit <emphasis>$JBOSS_HOME/server/default/conf/props/jmx-console-roles.properties</emphasis> file and make it contain: + + <programlisting> + <![CDATA[ +admin=JBossAdmin,HttpInvoker,Admin]]> + </programlisting> + + This file is a simple identity store for this web application authentication. It will make user <emphasis>admin</emphasis> belongs to <emphasis>Admin</emphasis> role. + </para> + </listitem> + <listitem> + <para>Deploy JBoss Portal</para> + </listitem> + <listitem> + <para>Run JBoss Application Server</para> + </listitem> + <listitem> + <para>Now you can check that when you go to + <itemizedlist> + <listitem><para> + <emphasis>http://localhost:8080/portal</emphasis></para> + </listitem> + <listitem> + <para> <emphasis>http://localhost:8080/jmx-console</emphasis></para> + </listitem> + </itemizedlist> + you need to authenticate separately into each of those web applications. + </para> + </listitem> + <listitem> + <para>Shutdown Application Server</para> + </listitem> + <listitem> + <para> + Uncomment the following line + <programlisting><![CDATA[<Valve className=’org.apache.catalina.authenticator.SingleSignOn’/>]]></programlisting> + in the <literal>$JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xml</literal> file. + More information can be found <ulink url="http://www.jboss.org/wiki/Wiki.jsp?page=SingleSignOn">h...;. + </para> + <para> + Run JBoss Application Server. + </para> + </listitem> + </orderedlist> + <para> + Now if you log into portal as user <emphasis>admin</emphasis> with password <emphasis>admin</emphasis>, you won't + be asked for credentials when accessing <emphasis>jmx-console</emphasis>. This should work in both directions. + </para> + <note><title>Note</title><para>Please note that in this example <emphasis>jmx-console</emphasis> uses <emphasis>BASIC</emphasis> authentication method. + This means that user credentials are cached on the client side by browser and passed on each request. Once authenticated to clear + authentication cache you may need to restart browser.</para></note> + </section> + </section> + <section> + <title>CAS - Central Authentication Service</title> + <para>This Single Sign On plugin enables seamless integration between JBoss Portal and the CAS Single Sign On Framework. + Details about CAS can be found <ulink url="http://www.ja-sig.org/products/cas/">here</ulink>... + <section> + <title>Integration steps</title> + <note><title>Note</title><para>The steps below assume that CAS server and JBoss Portal will be deployed on the same JBoss Application Server instance. + CAS will be configured to leverage identity services exposed by JBoss Portal to perform authentication. Procedure may be + slightly different for other deployment scenarios. Both JBoss Portal and CAS will need to be configured to authenticate against + same database or LDAP server. Please see CAS documentation to learn how to setup it up against proper identity store.</para></note> +<note><title>Note</title><para>Configuration below assumes that JBoss Application Server is HTTPS enabled and operates on standard ports: 80 (for HTTP) and 443 (for HTTPS).</para></note> + + <orderedlist> + <listitem> + <para>Install CAS server (v 3.0.7). This should be as simple as deploying single <emphasis>cas.war</emphasis> file.</para> + </listitem> + <listitem> + <para> Copy <emphasis>portal-identity-lib.jar</emphasis> and <emphasis>portal-identity-sso-lib.jar</emphasis> files from + <emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/lib</emphasis> to + <emphasis>$JBOSS_HOME/server/default/deploy/cas.war/WEB-INF/lib</emphasis>.</para> + </listitem> + <listitem> + <para> Edit <emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/context.xml</emphasis> file and enable proper Apache Tomcat Valve + by uncommenting following lines: + <programlisting> + <![CDATA[ +<Valve className="org.jboss.portal.identity.sso.cas.CASAuthenticationValve" + casLogin="https://localhost/cas/login" + casValidate="https://localhost/cas/serviceValidate" + casServerName="localhost" + authType="FORM" +/> + ]]> + </programlisting> + Update valve options as follow: + <itemizedlist> + <listitem> + <para> <emphasis>casLogin: </emphasis> URL of your CAS Authentication Server</para> + </listitem> + <listitem> + <para> <emphasis>casValidate: </emphasis> URL of your CAS Authentication Server validation service</para> + </listitem> + <listitem> + <para> <emphasis>casServerName:</emphasis> the hostname:port combination of your CAS Authentication Server</para> + </listitem> + </itemizedlist> + <note><title>Note</title><para>CAS client requires to use SSL connection. To learn how to setup JBoss Application Server to use HTTPS see here</para></note> + </para> + </listitem> + <listitem> + <para> Copy <emphasis>casclient.jar</emphasis> into <emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/lib</emphasis>. + You can download this file from CAS homepage or from JBoss repository under <emphasis>http://repository.jboss.com/cas/3.0.7/lib/</emphasis> + <note><title>Note</title><para>The CAS engine does not accept self-signed SSL certificates. This requirement is fine for production use where a production + level SSL certificate is available. However, for testing purposes, this can get a little annoying. Hence, if you are having this issue, + you can use <emphasis>casclient-lenient.jar</emphasis> instead.</para></note> + </para> + </listitem> + <listitem> + <para> Edit <emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/META-INF/jboss-service.xml</emphasis> file and uncomment following lines: + <programlisting> + <![CDATA[ +<mbean + code="org.jboss.portal.identity.sso.cas.CASAuthenticationService" + name="portal:service=Module,type=CASAuthenticationService" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <depends>portal:service=Module,type=IdentityServiceController</depends> + <attribute name="HavingRole"></attribute> +</mbean> + ]]> + </programlisting> + This will expose special service in JBoss Portal that can be leveraged by CAS AuthenticationHandler if the server is deployed on the same + application server instance. This AuthenticationHandler will be enabled in next 2 steps.</para> + </listitem> + <listitem> + <para> Edit <emphasis>$JBOSS_HOME/server/default/deploy/cas.war/WEB-INF/deployerConfigContext.xml</emphasis> and add following line in the + <emphasis>authenticationHandlers</emphasis> section: + <programlisting> + <![CDATA[ +<bean class="org.jboss.portal.identity.sso.cas.CASAuthenticationHandler" /> + ]]> + </programlisting> + This can replace default <emphasis>SimpleTestUsernamePasswordAuthenticationHandler</emphasis> so whole part of this config file can look + as follows: + + <programlisting> + <![CDATA[<property name="authenticationHandlers"> + <list> + <!-- + | This is the authentication handler that authenticates services by means of callback via SSL, thereby validating + | a server side SSL certificate. + +--> + <bean + class="org.jasig.cas.authentication.handler.support.HttpBasedServiceCredentialsAuthenticationHandler"> + <property + name="httpClient" + ref="httpClient" /> + </bean> + + <!-- + | This is the authentication handler declaration that every CAS deployer will need to change before deploying CAS + | into production. The default SimpleTestUsernamePasswordAuthenticationHandler authenticates UsernamePasswordCredentials + | where the username equals the password. You will need to replace this with an AuthenticationHandler that implements your + | local authentication strategy. You might accomplish this by coding a new such handler and declaring + | edu.someschool.its.cas.MySpecialHandler here, or you might use one of the handlers provided in the adaptors modules. + +--> + <bean class="org.jboss.portal.identity.sso.cas.CASAuthenticationHandler" /> + </list> +</property>]]> + </programlisting> + </para> + </listitem> + </orderedlist> + + <para> + To test the integration: + <itemizedlist> + <listitem><para>Go to your portal. Typically, http://localhost:8080/portal</para></listitem> + <listitem><para>Click on the "Login" link on the main portal page</para></listitem> + <listitem><para>This should bring up the CAS Authentication Server's login screen instead of the default JBoss Portal login screen</para></listitem> + <listitem><para>Input your portal username and password. For built-in portal login try user:user or admin:admin</para></listitem> + <listitem><para>If login is successful, you should be redirected back to the portal with the appropriate user logged in</para></listitem> + </itemizedlist> + </para> + + </section> + </section> + <section> + <title><trademark class="trade">Java</trademark> Open Single Sign-On (JOSSO)</title> + <para>JBoss Portal enables seamless integration with JOSSO server. More details on JOSSO can be found + <ulink url="http://www.josso.org/">here</ulink></para> + <note><title>Note</title><para>The steps below assume that JOSS server and JBoss Portal will be deployed on the same JBoss Application Server instance. + JOSSO will be configured to leverage identity services exposed by JBoss Portal to perform authentication. Procedure may be + slightly different for other deployment scenarios. Both JBoss Portal and JOSSO will need to be configured to authenticate against + same database or LDAP server. Please see JOSSO documentation to learn how to setup it up against proper identity store.</para></note> +<note><title>Note</title><para>Configuration below assumes that JOSSO is already installed and deployed in the JBoss Application Server. This involves adding proper jar files + into the classpath and altering several configuration files (adding Apache Tomcat Valves, security realm and specific JOSSO configuration files). + For JBoss setup please refer to JOSSO <ulink url="http://www.josso.org/jboss4-howto.html">documentation&l... + <section> + <title>Integration steps</title> + + <para> + <orderedlist> + <listitem> + <para> Copy <emphasis>portal-identity-lib.jar</emphasis> and <emphasis>portal-identity-sso-lib.jar</emphasis> files from + <emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/lib</emphasis> to + <emphasis>$JBOSS_HOME/server/default/deploy/josso.ear/josso.war/WEB-INF/lib</emphasis>.</para> + </listitem> + <listitem> + <para> Edit <emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/context.xml</emphasis> file and enable proper Apache Tomcat Valve + by uncommenting following lines: + <programlisting> + <![CDATA[ +<Valve className="org.jboss.portal.identity.sso.josso.JOSSOLogoutValve"/> + ]]> +</programlisting></para> + </listitem> + <listitem> + <para>Edit <emphasis>$JBOSS_HOME/server/default/config/josso-agent-config.xml</emphasis> and mapping for portal web application: + <programlisting> + <![CDATA[ +<partner-apps> + + ... + + <partner-app> + <context>/portal</context> + </partner-app> + + ... + + </partner-apps> + ]]> + </programlisting> + Complete config file can look as follows: + <programlisting> + <![CDATA[ +<?xml version="1.0" encoding="ISO-8859-1" ?> +<agent> + <class>org.josso.jb4.agent.JBossCatalinaSSOAgent</class> + <gatewayLoginUrl>http://localhost:8080/josso/signon/login.do</gatewayLoginUrl> + <gatewayLogoutUrl>http://localhost:8080/josso/signon/logout.do</gatewayLogoutUrl> + <service-locator> + <class>org.josso.gateway.WebserviceGatewayServiceLocator</class> + <endpoint>localhost:8080</endpoint> + </service-locator> + <partner-apps> + <partner-app> + <context>/partnerapp</context> + </partner-app> + <partner-app> + <context>/portal</context> + </partner-app> + </partner-apps> +</agent> + ]]> +</programlisting></para> + </listitem> + <listitem> + <para> Edit <emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/login.jsp</emphasis> and + <emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/erros.jsp</emphasis> and uncomment following line: + <programlisting> + <![CDATA[ +<% + response.sendRedirect(request.getContextPath() + "/josso_login/"); +%> + ]]> + </programlisting> + (make sure to remove java style comment '/* */' - not the xml one).</para> + </listitem> + <listitem> + <para> Edit <emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/META-INF/jboss-service.xml</emphasis> file and uncomment following lines: + <programlisting> + <![CDATA[ +<mbean + code="org.jboss.portal.identity.sso.josso.JOSSOIdentityServiceImpl" + name="portal:service=Module,type=JOSSOIdentityService" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <depends>portal:service=Module,type=IdentityServiceController</depends> +</mbean> + ]]> + </programlisting> + This will expose a special service in JBoss Portal that can be leveraged by JOSSO Credential and Identity Stores if the server is deployed on the same + application server instance.</para> + </listitem> + <listitem> + <para> Edit <emphasis>$JBOSS_HOME/server/default/deploy/josso.ear/josso.war/WEB-INF/classes/josso-gateway-config.xml</emphasis> and configure following elements: + <itemizedlist> + <listitem> + <para> <emphasis>Credential Store: </emphasis> + <programlisting> + <![CDATA[ +<!-- Basic Authentication Scheme --> +<authentication-scheme> + <name>basic-authentication</name> + <class>org.josso.auth.scheme.BindUsernamePasswordAuthScheme</class> + + <!-- ================================================= --> + <!-- JBoss Portal Credential Store --> + <!-- ================================================= --> + <credential-store> + <class>org.jboss.portal.identity.sso.josso.JOSSOIdentityStore</class> + </credential-store> + + + <!-- ================================================= --> + <!-- Credential Store Key adapter --> + <!-- ================================================= --> + <credential-store-key-adapter> + <class>org.josso.gateway.identity.service.store.SimpleIdentityStoreKeyAdapter</class> + </credential-store-key-adapter> + +</authentication-scheme> + ]]> +</programlisting></para> + </listitem> + <listitem> + <para> <emphasis>SSO Identity Store: </emphasis> + <programlisting> + <![CDATA[ +<sso-identity-manager> + + <class>org.josso.gateway.identity.service.SSOIdentityManagerImpl</class> + + <!-- ================================================= --> + <!-- JBoss Portal Credential Store --> + <!-- ================================================= --> + <sso-identity-store> + <class>org.jboss.portal.identity.sso.josso.JOSSOIdentityStore</class> + </sso-identity-store> + + <!-- ================================================= --> + <!-- Identity Store Key adapter --> + <!-- ================================================= --> + <sso-identity-store-key-adapter> + <class>org.josso.gateway.identity.service.store.SimpleIdentityStoreKeyAdapter</class> + </sso-identity-store-key-adapter> + +</sso-identity-manager> + ]]> +</programlisting></para> + </listitem> + </itemizedlist> + </para> + </listitem> + </orderedlist> + </para> + <para> + To test the integration: + <itemizedlist> + <listitem><para>Go to your portal. Typically, http://localhost:8080/portal</para></listitem> + <listitem><para>Click on the "Login" link on the main portal page</para></listitem> + <listitem><para>This should bring up the JOSSO login screen instead of the default JBoss Portal login screen</para></listitem> + <listitem><para>Input your portal username and password. For built-in portal login try user:user or admin:admin</para></listitem> + <listitem><para>If login is successful, you should be redirected back to the portal with the appropriate user logged in</para></listitem> + </itemizedlist> + </para> + </section> + </section> + +</chapter> + <chapter id="cmsPortlet"> + <!--<chapterinfo> + <author> + <firstname>Roy</firstname> + <surname>Russo</surname> + </author> + <author> + <firstname>Thomas</firstname> + <surname>Heute</surname> + </author> + </chapterinfo>--> + <title>CMS Portlet</title> + <para>JBoss Portal packages a Web Content Management System capable of serving and allowing + administration of web content. This chapter describes the CMS Portlet which is responsible for + serving resources requested, the following chapter describes the CMSAdmin Portlet and all + administration functionality.</para> + <mediaobject> + <imageobject> + <imagedata fileref="images/cms/cms_ss_1.gif" align="center" valign="middle" scalefit="1"/> + </imageobject> +</mediaobject> + <section> + <title>Introduction</title> + <para>The CMS Portlet displays content from the file store inside a portlet window, or, in the + case of binary content, outside of the portlet window altogether.</para> + </section> + <section> + <title>Features</title> + <para>The CMSPortlet handles all requests for all content types.</para> + <para>The methodology of serving content within the CMSPortlet, allows for some beneficial + features, like:</para> + <orderedlist> + + <listitem><para>Search-engine friendly URLs: http://domain/[portal]/content/company.html</para></listitem> + <listitem><para>Serve binaries with simple urls independent of the portal: + http://domain/content/products.pdf</para></listitem> + <listitem><para>Deploy several instances of the CMSPortlet on any page and configure them to + display different start pages.</para></listitem> + <listitem><para>Localization support: CMSPortlet will display content based on the user request + locale, or display content using the default locale setting.</para></listitem> + </orderedlist> + </section> + <section id="configuration-cms_content"> + <title>CMS content</title> + <para>Since 2.6 displaying CMS content in the portal is done using the new content integration + feature. Each window of the portal can be configured to display CMS content directly instead of + having to configure the CMS portlet as it used to be. + </para> + <section> + <title>Configuring a window to display CMS content</title> + <para>Showing CMS content in a portal window can be done in the deployment descriptor quite easily + <programlisting><![CDATA[<window> + <window-name>MyCMSWindow</window-name> + <content> + <content-type>cms</content-type> + <content-uri>/default/index.html</content-uri> + </content> + <region>center</region> + <height>1</height> +</window> +]]></programlisting> + At the first display of the window, the content is initialized with the content uri value. + When the user clicks on a link that navigates to another CMS file, the CMS file will be shown in the + same window. + </para> + </section> + </section> + <section> + <title>CMS Configuration</title> + <section> + <title>Display CMS content</title> + <para>Since 2.6 displaying CMS content in the portal is done using the new content integration + feature. + + + The portal is also able to map urls content to the CMS through a specific window. + The CMS portlet default page is defined as a preference and can be overridden like any + other preference up to the user's preference level. The default CMS portlet displayed + when you install JBoss Portal for the first time is describe in the following file: + <emphasis>jboss-portal.sar/portal-core.war/WEB-INF/portlet.xml</emphasis> + . + </para> + <programlisting><![CDATA[<portlet-preferences> + <preference> + <name>indexpage</name> + <value>/default/index.html</value> + </preference> +</portlet-preferences>]]></programlisting> + <para> + The preference key is "indexpage". To change the default page, just make sure to create + an HTML document using the CMS Admin portlet then change the value of "indexpage" to + the corresponding path. + </para> + </section> + <section> + <title>Service Configuration</title> + <section> + <title>Tuning Apache Jackrabbit</title> + <para>JBoss Portal uses Apache Jackrabbit as its Java Content Repository implementation. + Configuration of the service descriptor, allows for changing many of the variables + associated with the service.</para> + <para>Here is the default configuration for the CMS repository found under + <literal>portal-cms.sar/META-INF-INF/jboss-service.xml</literal> + </para> + <programlisting><![CDATA[... +<attribute name="DoChecking">true</attribute> +<attribute name="DefaultContentLocation">portal/cms/conf/default-content/default/</attribute> +<attribute name="DefaultLocale">en</attribute> +<attribute name="RepositoryName">PortalRepository</attribute> +<attribute name="HomeDir">${jboss.server.data.dir}${/}portal${/}cms${/}conf</attribute>]]> +...</programlisting> + <para>Below is a list of items found in the service descriptor and their definitions. Only + items commonly changed are covered here and it is recommended you do not change any others + unless you are very brave.</para> + <para> + <itemizedlist> + <listitem><para> + <emphasis role="bold">DoChecking:</emphasis> + Should the portal attempt to check for the + existence of the repository configuration files and default content on startup?</para> + </listitem> + <listitem> + <para><emphasis role="bold">DefaultContentLocation:</emphasis> + Location of the default content used to + pre-populate the repository.</para> + </listitem> + <listitem> + <para><emphasis role="bold">DefaultLocale:</emphasis> + Two-letter abbreviation of the default + locale the portal should use when fetching content for users. A complete ISO-639 list + can be found + <ulink url="http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt"&g... + .</para> + </listitem> + <listitem> + <para> <emphasis role="bold">HomeDir:</emphasis> + Location of configuration information for the + repository when in 100% FileSystem store mode. Otherwise, its in the database.</para> + </listitem> + </itemizedlist> + </para> + </section> + <section> + <title>Changing the url under which the content should be accessible</title> + <para> + By default, the content will be accessible to a url like this: http://www.example.com/content/[...], if + you need or prefer to change "content" to something else you will need to edit the following file: + <literal>portal-cms.sar/META-INF-INF/jboss-service.xml</literal> + and change the value of Prefix to something else. Please note that you cannot change it to "nothing", you + need to provide a value. + </para> + <programlisting><![CDATA[... +<mbean + code="org.jboss.portal.core.cms.CMSObjectCommandFactory" + name="portal:commandFactory=CMSObject" + xmbean-dd="" + xmbean-code="org.jboss.portal.common.system.JBossServiceModelMBean"> + <xmbean/> + <attribute name="Prefix">content</attribute> + <attribute name="TargetWindowRef">default.default.CMSPortletWindow</attribute> + <depends optional-attribute-name="Factory" proxy-type="attribute"> + portal:commandFactory=Delegating + </depends> + <depends optional-attribute-name="CMSService" proxy-type="attribute"> + portal:service=CMS + </depends> +</mbean> +...]]> + </programlisting> + <itemizedlist> + <listitem> + <para><emphasis role="bold">Prefix:</emphasis> + This is the context path prefix that will + trigger the portal to render content. By default, navigating to a URL such as + http://localhost:8080/[portal_context]/content/Test.PDF will trigger the portal to + display the PDF isolated from the portal pages. The path following the + <emphasis>Prefix</emphasis> + has to be absolute when fetching content.</para> + </listitem> + </itemizedlist> + </section> + </section> + <section id="configuration-cms"> + <title>Configuring the Content Store Location</title> + <para>By default, the JBoss Portal CMS stores all node properties, references, and binary + content in the database, using the portal datasource. The location of some of these items + is configurable, and there are 3 options: + <itemizedlist> + <listitem> + <para> + <xref linkend="configuration-cms_fs"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="configuration-cms_db"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="configuration-cms_mixed"/> + </para> + </listitem> + </itemizedlist> + </para> + <section id="configuration-cms_fs"> + <title>100% Filesystem Storage</title> + <para>To enable 100% Filesystem storage, you must edit the file: + <emphasis>jboss-portal.sar/portal-cms.sar/META-INF/jboss-service.xml</emphasis> + . You will note that the file is set to use the HibernateStore + and HibernatePersistenceManager classes, by default. To have the CMS use 100% file + system storage, simply comment these blocks. Then, you should uncomment to use the + LocalFileSystem and XMLPersistenceManager classes. Follow these steps to activate 100% FS storage: + </para> + <para> + <orderedlist> + <listitem> + <para> + Comment out the following blocks (there are 3 in total): + <programlisting><![CDATA[ +<!-- HibernateStore: uses RDBMS + Hibernate for storage --> +<FileSystem class="org.jboss.portal.cms.hibernate.HibernateStore"> +... +</FileSystem> +]]></programlisting> + And uncomment the blocks under them (there are 3 in total): + <programlisting><![CDATA[ +<!-- LocalFileSystem: uses FileSystem for storage. --> +<FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem"> +... +</FileSystem>]]></programlisting> + </para> + </listitem> + <listitem> + <para> + Now comment out the following blocks (there are 2 in total): + <programlisting><![CDATA[ +<!-- HibernatePersistentManager: uses RDBMS + Hibernate for storage --> +<PersistenceManager class="org.jboss.portal.cms.hibernate.state.HibernatePersistenceManager"> +... +</PersistenceManager>]]></programlisting> + And uncomment the blocks under them (there are 2 in total): + <programlisting><![CDATA[ +<!-- XMLPersistenceManager: uses FileSystem for storage --> +<PersistenceManager class="org.apache.jackrabbit.core.state.xml.XMLPersistenceManager"/> +]]></programlisting> + </para> + </listitem> + </orderedlist> + </para> + <para> + <warning><title>Caution</title><para> + If you do any change at the workspaces configuration you will need to delete the file + <emphasis>$JBOSS_HOME/server/xxx/data/portal/cms/conf/workspaces/default/workspace.xml</emphasis> + before restarting JBoss or redeploying JBoss Portal. If you forget to do that, the changes + won't affect the CMS. + For the same reason, you also need to delete that file if you recompile JBoss Portal after + changing the name of the datasource. + Note that on a cluster environment, you need to remove that file (if it exists) on all the nodes. + </para></warning> + </para> + </section> + <section id="configuration-cms_db"> + <title>100% Database Storage</title> + <para>This is the default configuration for the CMS store. Please view the original + <emphasis>jboss-portal.sar/portal-cms.sar/META-INF/jboss-service.xml</emphasis> + , for guidance on how to reset it. + </para> + </section> + <section id="configuration-cms_mixed"> + <title>Mixed Storage</title> + <para>Mixed storage consists of meta-data being stored in the DB and blobs being stored on the Filesystem. + This is the recommended setting for those of you that serve large files or stream media content.</para> + <para> + Setting the repository this way is simple. Change every instance in the file + <emphasis>jboss-portal.sar/portal-cms.sar/META-INF/jboss-service.xml</emphasis> + , from: + <programlisting><![CDATA[<param name="externalBLOBs" value="false"/>]]></programlisting> + to: + <programlisting><![CDATA[<param name="externalBLOBs" value="true"/>]]></programlisting> + </para> + <para> + <warning><title>Caution</title><para> + If you do any change at the workspaces configuration you will need to delete the file + <emphasis>$JBOSS_HOME/server/xxx/data/portal/cms/conf/workspaces/default/workspace.xml</emphasis> + before restarting JBoss or redeploying JBoss Portal. If you forget to do that, the changes + won't affect the CMS. + For the same reason, you also need to delete that file if you recompile JBoss Portal after + changing the name of the datasource. + Note that on a cluster environment, you need to remove that file (if it exists) on all the nodes. + </para></warning> + </para> + </section> + </section> + </section> + <!-- <section> + <title>Portlet Preferences</title> + <para>TODO</para> + </section>--> + <section> + <title>Localization Support</title> + <para>The CMS Portlet now serves content based on the user's locale setting. For example: if a + user's locale is set to Spanish in his browser, and he requests URL: + <emphasis>default/index.html</emphasis> + , the CMSPortlet will first try and retrieve the + Spanish version of that file. If a Spanish version is not found, it will then try and + retrieve the default language version set for the CMSPortlet. + </para> + </section> + <section> + <title>CMS Service</title> + <para> + The CMS portlet calls a CMS service that can be reused in your own portlets. + </para> + <section> + <title>CMS Interceptors</title> + <para> + Since JBoss Portal 2.4 you can add your own interceptor stack to the CMS service. + The interceptors are called around each command (Get a file, write a file, create a folder...), + this is a very easy way to customize some actions based on your needs. + </para> + <para> + To create your own interceptor you just need to extend the + <literal>org.jboss.portal.cms.CMSInterceptor</literal> + class and provide the content of the + <literal>invoke(JCRCommand)</literal> + method. Do not forget to make a call + to + <literal>JCRCommand.invokeNext()</literal> + or the command will never be executed. + </para> + <para> + JBoss Portal relies on the interceptor mechanism to integrate its Fine Grained Security Service and + the Publish/Approve Workflow Service + </para> + <para> + To add or remove an interceptor, you just need to edit the following file: + <literal>portal-cms-sar/META-INF/jboss-service.xml</literal>. + It works the same way as the server interceptor, for each interceptor you need to define an MBean then add it + to the cms interceptor stack. For example, if you have the 2 default interceptors, you should have the following + lines in the jboss-service.xml file: + <programlisting><![CDATA[<!-- ACL Security Interceptor --> +<mbean code="org.jboss.portal.cms.impl.interceptors.ACLInterceptor" + name="portal:service=Interceptor,type=Cms,name=ACL" xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean /> + <attribute name="JNDIName"> + java:/portal/cms/ACLInterceptor + </attribute> + <attribute name="CmsSessionFactory"> + java:/portal/cms/CMSSessionFactory + </attribute> + <attribute name="IdentitySessionFactory"> + java:/portal/IdentitySessionFactory + </attribute> + <attribute name="DefaultPolicy"> + <policy> + <!-- permissions on the root cms node --> + <criteria name="path" value="/"> + <permission name="cms" action="read"> + <role name="Anonymous" /> + </permission> + <permission name="cms" action="write"> + <role name="User" /> + </permission> + <permission name="cms" action="manage"> + <role name="Admin" /> + </permission> + </criteria> + <!-- permissions on the default cms node --> + <criteria name="path" value="/default"> + <permission name="cms" action="read"> + <role name="Anonymous" /> + </permission> + <permission name="cms" action="write"> + <role name="User" /> + </permission> + <permission name="cms" action="manage"> + <role name="Admin" /> + </permission> + </criteria> + <!-- permissions on the private/protected node --> + <criteria name="path" value="/default/private"> + <permission name="cms" action="manage"> + <role name="Admin" /> + </permission> + </criteria> + </policy> + </attribute> + <depends optional-attribute-name="AuthorizationManager" + proxy-type="attribute"> + portal:service=AuthorizationManager,type=cms + </depends> + <depends>portal:service=Hibernate,type=CMS</depends> + <depends> + portal:service=Module,type=IdentityServiceController + </depends> +</mbean> + +<!-- Approval Workflow Interceptor --> +<mbean + code="org.jboss.portal.cms.impl.interceptors.ApprovalWorkflowInterceptor" + name="portal:service=Interceptor,type=Cms,name=ApprovalWorkflow" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean /> + <attribute name="JNDIName"> + java:/portal/cms/ApprovalWorkflowInterceptor + </attribute> + <depends>portal:service=Hibernate,type=CMS</depends> +</mbean> + +<!-- CMS Interceptor Registration --> +<mbean + code="org.jboss.portal.server.impl.invocation.JBossInterceptorStackFactory" + name="portal:service=InterceptorStackFactory,type=Cms" xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean /> + <depends-list optional-attribute-name="InterceptorNames"> + <depends-list-element> + portal:service=Interceptor,type=Cms,name=ACL + </depends-list-element> + <depends-list-element> + portal:service=Interceptor,type=Cms,name=ApprovalWorkflow + </depends-list-element> + </depends-list> +</mbean> + ]]> + </programlisting> + The first two MBeans define the interceptors and the third MBean, define which interceptors to add to + the CMS service. + </para> + <para> + If you create your own interceptor <literal>org.example.myCMSInterceptor</literal>, the service descriptor file will look like: + <programlisting><![CDATA[<mbean code="org.example.myCMSInterceptor" + name="portal:service=Interceptor,type=Cms,name=MyName" xmbean-dd="" + xmbean-code="org.jboss.portal.common.system.JBossServiceModelMBean"> + <xmbean /> +</mbean> + +<!-- ACL Security Interceptor --> +<mbean code="org.jboss.portal.cms.impl.interceptors.ACLInterceptor" + name="portal:service=Interceptor,type=Cms,name=ACL" xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean /> + <attribute name="JNDIName"> + java:/portal/cms/ACLInterceptor + </attribute> + <attribute name="CmsSessionFactory"> + java:/portal/cms/CMSSessionFactory + </attribute> + <attribute name="IdentitySessionFactory"> + java:/portal/IdentitySessionFactory + </attribute> + <attribute name="DefaultPolicy"> + <policy> + <!-- permissions on the root cms node --> + <criteria name="path" value="/"> + <permission name="cms" action="read"> + <role name="Anonymous" /> + </permission> + <permission name="cms" action="write"> + <role name="User" /> + </permission> + <permission name="cms" action="manage"> + <role name="Admin" /> + </permission> + </criteria> + <!-- permissions on the default cms node --> + <criteria name="path" value="/default"> + <permission name="cms" action="read"> + <role name="Anonymous" /> + </permission> + <permission name="cms" action="write"> + <role name="User" /> + </permission> + <permission name="cms" action="manage"> + <role name="Admin" /> + </permission> + </criteria> + <!-- permissions on the private/protected node --> + <criteria name="path" value="/default/private"> + <permission name="cms" action="manage"> + <role name="Admin" /> + </permission> + </criteria> + </policy> + </attribute> + <depends optional-attribute-name="AuthorizationManager" + proxy-type="attribute"> + portal:service=AuthorizationManager,type=cms + </depends> + <depends>portal:service=Hibernate,type=CMS</depends> + <depends> + portal:service=Module,type=IdentityServiceController + </depends> +</mbean> + +<!-- Approval Workflow Interceptor --> +<mbean + code="org.jboss.portal.cms.impl.interceptors.ApprovalWorkflowInterceptor" + name="portal:service=Interceptor,type=Cms,name=ApprovalWorkflow" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean /> + <attribute name="JNDIName"> + java:/portal/cms/ApprovalWorkflowInterceptor + </attribute> + <depends>portal:service=Hibernate,type=CMS</depends> +</mbean> +<mbean + code="org.jboss.portal.server.impl.invocation.JBossInterceptorStackFactory" + name="portal:service=InterceptorStackFactory,type=Cms" xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean /> + <depends-list optional-attribute-name="InterceptorNames"> + <depends-list-element> + portal:service=Interceptor,type=Cms,name=ACL + </depends-list-element> + <depends-list-element> + portal:service=Interceptor,type=Cms,name=ApprovalWorkflow + </depends-list-element> + </depends-list> +</mbean> + +<!-- CMS Interceptor Registration --> +<mbean + code="org.jboss.portal.server.impl.invocation.JBossInterceptorStack" + name="portal:service=InterceptorStack,type=Cms" xmbean-dd="" + xmbean-code="org.jboss.portal.common.system.JBossServiceModelMBean"> + <xmbean /> + <depends-list optional-attribute-name="InterceptorNames"> + <depends-list-element> + portal:service=Interceptor,type=Cms,name=ACL + </depends-list-element> + <depends-list-element> + portal:service=Interceptor,type=Cms,name=ApprovalWorkflow + </depends-list-element> + <depends-list-element> + portal:service=Interceptor,type=Cms,name=MyName + </depends-list-element> + </depends-list> +</mbean> +]]></programlisting> + </para> + <note> + <para> + The interceptor order is important ! + </para> + </note> + <para> + To check that the interceptors have been correctly added, you can check the JMX console, by going to: + <literal>http://localhost.localdomain:8080/jmx-console/HtmlAdaptor?action=inspectMBean&amp;name=portal%3Aservice%3DInterceptorStack%2Ctype%3DCms</literal> + You should notice all the interceptors in the attribute "interceptors". + </para> + </section> + </section> +</chapter> + <chapter id="workflow"> + <!-- <chapterinfo> + <author> + <firstname>Sohil</firstname> + <surname>Shah</surname> + <email>sshah @ redhat dot com</email> + </author> + </chapterinfo>--> + <title>Portal Workflow</title> + <para> + JBoss Portal packages a Workflow Service based on jBPM. This service provides you with the jBPM services that your + portal can use to build out the end-user/application workflows that should meet your portal's requirements. + </para> + <section> + <title>jBPM Workflow Engine Integration</title> + <para> + The jBPM Workflow service is packaged as an mbean and takes care of all the low-level jBPM related functions. + The configuration is found in <filename>portal-workflow.sar/META-INF/jboss-service.xml</filename>. + </para> + </section> + <section> + <title>CMS Publish/Approve Workflow Service</title> + <para> + The CMS Publish/Approval Workflow feature is turned on by default, so that every file that is created or + updated needs to go through an <emphasis role="bold">approval process</emphasis> before it can be published to + go live. The current implementation creates a pending queue for managers. The managers can then either approve + or reject the publishing of the document in question. + </para> + <section> + <title>How to activate this feature?</title> + <para> + The CMS Publish/Approval Workflow feature can be activated by uncommenting the + <literal>ApprovePublishWorkflow</literal> attribute of the <literal>portal:service=CMS</literal> mbean in + <filename>portal-cms.sar/META-INF/jboss-service.xml</filename>: + <programlisting><![CDATA[ +<mbean + code=&quot;@cms.service.code(a)&quot; + name="portal:service=CMS" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + + ... + + <!-- Add this to activate publish/approval workflow integration --> + <!-- <depends optional-attribute-name="ApprovePublishWorkflow" proxy-type="attribute">portal:service=ApprovePublish,type=Workflow</depends> --> + + ... +</mbean>]]></programlisting> + </para> + </section> + <section> + <title>How to configure this feature?</title> + <para> + The workflow service can be configured by editing the <literal>portal:service=ApprovePublish,type=Workflow</literal> + mbean found in <filename>portal-cms.sar/META-INF/jboss-service.xml</filename>. + <programlisting> + <![CDATA[ +<!-- ApprovePublish workflow service --> + <mbean + code="org.jboss.portal.cms.workflow.ApprovePublishImpl" + name="portal:service=ApprovePublish,type=Workflow" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <depends optional-attribute-name="WorkflowService" proxy-type="attribute"> + portal:service=Workflow,type=WorkflowService + </depends> + <depends optional-attribute-name="IdentityServiceController" proxy-type="attribute"> + portal:service=Module,type=IdentityServiceController + </depends> + <!-- JBPM process definition --> + <attribute name="Process"> + <!-- cms approval workflow --> + <process-definition name="approval_workflow"> + <start-state> + <transition to="request_approval"/> + </start-state> + <task-node name="request_approval" signal="first"> + <task name="approve_publish"> + <assignment class="org.jboss.portal.cms.workflow.PublishAssignmentHandler"/> + <event type="task-start"> + <action class="org.jboss.portal.cms.workflow.FinalizePublish"/> + </event> + <exception-handler> + <action class="org.jboss.portal.cms.workflow.TaskExceptionHandler"/> + </exception-handler> + </task> + <transition name="approval" to="end"/> + <transition name="rejection" to="end"/> + </task-node> + <end-state name="end"/> + </process-definition> + </attribute> + <!-- + overwrite = false creates the process first time if does not exist, for + subsequent server restarts, this process definition remains in tact + + overwrite = true creates the process first time if does not exist, + for subsequent server restarts, it creates a new version of the process definition + which will be used for processes created from then onwards. Old processes created + for an older version of the definition remain in tact and use their corresponding + process definition. + + Typically use overwrite=false and overwrite=true only when a new process definition + related to this workflow needs to be deployed + --> + <attribute name="Overwrite">false</attribute> + <!-- + A comma separated list of portal roles that are designated + to act as workflow managers. They are allowed to + approve/reject content publish requests + --> + <attribute name="ManagerRoles">Admin</attribute> + <attribute name="JNDIName">java:portal/ApprovePublishWorkflow</attribute> + </mbean>]]></programlisting> + </para> + <para> + Of note in this configuration are the <literal>Process</literal> and <literal>ManagerRoles</literal> + attributes. The <literal>Process</literal> attribute is used to provide the jBPM process definition to be + followed by the workflow service during the approval process. This follows the standard jBPM syntax + for process definition. <literal>ManagerRoles</literal>, on the other hand, is a comma-delimited list of + user roles that are being marked as "managers" who can approve the publication of CMS documents. + </para> + </section> + </section> +</chapter> + <chapter id="navtabs"> + <!--<chapterinfo> + <author> + <firstname>Roy</firstname> + <surname>Russo</surname> + </author> + <author> + <firstname>Thomas</firstname> + <surname>Heute</surname> + </author> + </chapterinfo>--> + <title>Navigation Tabs</title> + <para>The navigation tabs allow users to navigate the portal pages. This section describes some of the functionality + available in configuring them. + <mediaobject> + <imageobject> + <imagedata fileref="images/navtabs/navtabs_ss.gif" align="center" valign="middle"/> + </imageobject> + </mediaobject> + </para> + <section> + <title>Explicit ordering of tabs</title> + <para>Explicit ordering of the tab display, is accomplished via page properties that are defined in your + <emphasis>*-object.xml</emphasis> + ( + <xref linkend="desc_objectxml"/> + ). Ordering is accomplished using the + <emphasis>order</emphasis> + tag at the page level as a page property. + <programlisting><![CDATA[ +<page> + <page-name>default</page-name> + <properties> + <property> + <name>order</name> + <value>1</value> + </property> + </properties> + ... +</page>]]></programlisting> + </para> + </section> + <section> + <title>Translating tab labels</title> + <para>Labels on tabs can be defined in multiple languages. Two different ways can be used, the first one consist at + defining several display name for page objects, the second one consists of defining a resource bundle where to find + the localized display-name. Both methods have advantages and drawbacks.</para> + <section> + <title>Method one: Multiple <literal>display-name</literal></title> + <para>In the <filename>*-object.xml</filename> descriptor under the <literal>page</literal> element, it is possible + to define a display-name per locale. Here is an example: + <programlisting><![CDATA[ +<page> + <page-name>News</page-name> + <display-name xml:lang="en">News</display-name> + <display-name xml:lang="it">Novita'</display-name> + <display-name xml:lang="es">Noticias</display-name> + <display-name xml:lang="fr">Actualités</display-name> + ... +</page> + ]]></programlisting> + Here we defined a display name for four different languages. The advantage of this method is that it is simple and the + display name is kept along the metadata. The drawback of this method is that if you may end up with different places + to keep your localized data. If you are using resource bundles for other elements, the second method might be simpler + when you add new supported languages. + </para> + </section> + <section> + <title>Defining a resource bundle and supported locales</title> + <para>If you are already using resource bundles for localization you may prefer to point to those files. To do so you + can define the name of your ressource bundle. The files should be in the classloader of the war containing the <filename>*-object.xml</filename> + where you define them, meaning in the same war file.</para> + <para>Here is an example: + <programlisting><![CDATA[ +<page> + <page-name>Weather</page-name> + <supported-locale>fr</supported-locale> + <supported-locale>en</supported-locale> + ... +</page> + ]]></programlisting> + With one or the other method, accessing the portal will now display the tab names with the preferred locale if a localized + value exists. + </para> + <warning><para>If you change the values in the descriptor (method 1) or in the resource bundles (method 2) you need to use + the <literal>&lt;if-exists&gt;overwrite&lt;/if-exists&gt;</literal> so that the values are updated</para></warning> + </section> + </section> +</chapter> + <chapter id="themeandlayouts"> + <!-- <chapterinfo> + <author> + <firstname>Martin</firstname> + <surname>Holzner</surname> + </author> + <author> + <firstname>Mark</firstname> + <surname>Fernandes</surname> + </author> + <author> + <firstname>Thomas</firstname> + <surname>Heute</surname> + </author> + </chapterinfo>--> + <title>Layouts and Themes</title> + <section> + <title>Overview</title> + <para>Portals usually render the markup fragments of several portlets, and aggregate these + fragments into one page that ultimately gets sent back as response. Each portlet on that + page will be decorated by the portal to limit the real estate the portlet has on the page, + but also to allow the portal to inject extra functionality on a per portlet basis. Classic + examples of this injection are the maximize, minimize and mode change links that will + appear in the portlet window , together with the title. + </para> + <para>Layouts and themes allow to manipulate the look and feel of the portal. Layouts are + responsible to render markup that will wrap the markup fragments produced by the individual + portlets. Themes, on the other hand, are responsible to style and enhance this markup. + </para> + <para>In JBoss Portal, layouts are implemented as a JSP or a Servlet. Themes are implemented using CSS Style sheets, <trademark class="trade">JavaScript</trademark> and images. The binding element between layouts and themes are the class and id attributes of the rendered markup. + </para> + <para>JBoss Portal has the concept of regions on a page. When a page is defined, and portlet + windows are assigned to the page, the region, and order inside the region, has to be + specified as well. For portal layouts this has significant meaning. It defines the top most + markup container that can wrap portlet content (other then the static markup in the JSP + itself). In other words: from a layout perspective all portlets of a page are assigned to + one or more regions. Each region can contain one or more portlets. To render the page + content to return from a portal request, the portal has to render the layout JSP, and for + each region, all the portlets in the region. + </para> + <para>Since the markup around each region, and around each portlet inside that region, is + effectively the same for all the pages of a portal, it makes sense to encapsulate it in its + own entity. + </para> + <para>To implement this encapsulation there are several ways:</para> + <itemizedlist> + + <listitem><para>JSP pages that get included from the layout JSP for each region/portlet</para></listitem> + <listitem><para>a taglib that allows to place region, window, and decoration tags into the layout JSP</para> + </listitem> + <listitem><para>a taglib that uses a pluggable API to delegate the markup generation to a set of classes</para> + </listitem> + </itemizedlist> + + <para> + In JBoss Portal you can currently see two out of these approaches, namely + the first and the last. Examples for the first can be found in the portal-core.war, + implemented by the nodesk and phalanx layouts. Examples for the third approach can be found + in the same war, implemented by the industrial and Nphalanx layout. What encapsulates the + markup generation for each region, window, and portlet decoration in this last approach is + what's called the RenderSet. + </para> + <para>The RenderSet consist of four interfaces that correspond with the four markup + containers that wrap the markup fragments of one of more portlets: + </para> + <itemizedlist> + + <listitem><para>Region</para></listitem> + <listitem><para>Window</para></listitem> + <listitem><para>Decoration</para></listitem> + <listitem><para>Portlet Content</para></listitem> + </itemizedlist> + + <para>While we want to leave it open to you to decide which way to implement your layouts and + themes, we strongly believe that the last approach is superior, and allows for far more + flexibility, and clearer separation of duties between portal developers and web designers. + </para> + <!-- + <para>Portal layouts also have the concept of a layout strategy. The layout strategy is a + pluggable API, and lets the layout developer have a last say about the content to be + rendered. The strategy is called right after the portal has determined what needs to be + rendered as part of the current request. So the strategy is invoked right between the point + where the portal knows what needs to be done, and before the actual work is initiated. The + strategy gets all the details about what is going to happen, and it can take measures to + influence those details. + <itemizedlist> + <para>Some simple examples of those measures are:</para> + <listitem>ommit one of the portlets from being rendered</listitem> + <listitem>change the portlet mode or window state of a portlet before it gets rendered</listitem> + <listitem>change the layout to be used for this request</listitem> + <listitem>...and many more</listitem> + </itemizedlist> + </para> + --> + <para>The last topic to introduce in this overview is the one of portal themes. A theme is a + collection of web design artifacts. It defines a set of CSS, JavaScript and image files + that together decide about the look and feel of the portal page. The theme can take a wide + spectrum of control over the look and feel. It can limit itself to decide fonts and colors, + or it can take over a lot more and decide the placement (location) of portlets and much + more. + </para> + </section> + <section> + <title>Header</title> + <section> + <title>Overview</title> + <para>The default header is divided into two parts, links to pages displayed as tabs and links + to navigate between portals and dahsboards as well as loggin in and out. Those two parts are + included into the template thanks to the layout as defined in <xref linkend="layouts"/>. + In fact, the region named, <literal>dashboardnav</literal> will include the navigation links, + while the region named <literal>navigation</literal> will include the navigation tabs. + It is then easy to hide one and/or the other by removing the corresponding inclusion in the + layout. + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/themeguide/portal-header.gif" scalefit="1"/> + </imageobject> + </mediaobject> + <para>Screenshot of the header with the 'renaissance' theme</para> + + <note><title>Note</title><para>Here, we use split content from rendering by using a CSS style sheet, it allows us to change the + display by switching the CSS without affecting the content. THe Maple theme will display the links + on the left side with a different font for example. THis is up to you to choose or not this approach</para> + </note> + <para>To customize the header there are several options detailed after. + <itemizedlist> + <listitem><para>The first option would simply require to modify + the theme CSS, by doing this you could change the fonts, the way tabs are rendered, colors and many + other things but not change the content.</para></listitem> + <listitem><para>The second option is to modify the provided JSP files, <literal>header.jsp</literal> and + <literal>tabs.jsp</literal>. It gives you more flexibility than the previous solution on modifying + the content. Links to legacy application could easily be added, URLs could be arranged differently, the CSS + approach could be replaced by good old HTML, CSS style names could be changed... The drawback of + this method compare to the next one is the limitation in what is accessible from the JSP.</para></listitem> + <!-- listitem>The third option is the most flexible and let you inject whatever you want, it consists in + replacing the default <literal>PageCustomizerInterceptor</literal> by your own.</listitem--> + </itemizedlist> + </para> + <section> + <title>Writing his own <trademark class="trade">JSP</trademark> pages</title> + <para>The content of those two parts are displayed thanks to two different <trademark class="trade">JSP</trademark> pages. By default + you would find those pages in the directory <literal>portal-core.war/WEB-INF/jsp/header/</literal>. + The file <literal>header.jsp</literal> is used to display the links that are displayed on the upper + right of the default theme. The file <literal>tabs.jsp</literal> is used to display the pages tabs + appearing on the left. + </para> + <para> Again, you have several choices, either to edit the included JSP files directly or create your own, + store them in a web application then edit the following file: <literal>jboss-portal.sar/META-INF/jboss-service.xml</literal>. + The interesting part in that file is the following: + <programlisting><![CDATA[<mbean + code="org.jboss.portal.core.aspects.controller.PageCustomizerInterceptor" + name="portal:service=Interceptor,type=Command,name=PageCustomizer" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <attribute name="TargetContextPath">/portal-core</attribute> + <attribute name="HeaderPath">/WEB-INF/jsp/header/header.jsp</attribute> + <attribute name="TabsPath">/WEB-INF/jsp/header/tabs.jsp</attribute> + <depends + optional-attribute-name="PortalAuthorizationManagerFactory" + proxy-type="attribute">portal:service=PortalAuthorizationManagerFactory</depends> +</mbean>]]></programlisting> + The three attributes are: + <itemizedlist> + <listitem><para>TargetContextPath: Defines the web application context where the JSP files are located</para></listitem> + <listitem><para>HeaderPath: Defines the location (in the web application previously defined) of the JSP in charge of writing the header links</para></listitem> + <listitem><para>TabsPath: Defines the location (in the web application previously defined) of the JSP in charge of writing the pages links (note that it doesn't have to be renderer as tabs)</para></listitem> + </itemizedlist> + </para> + <para>Writing the header JSP</para> + <para>A couple of request attributes are set so that they can be used by the JSP, here is the list of attributes and their meaning: + <itemizedlist> + <listitem><para><literal>org.jboss.portal.header.USER</literal>: A <literal>org.jboss.portal.identity.User</literal> object of the logged-in user, null if the user is not logged-in.</para></listitem> + <listitem><para><literal>org.jboss.portal.header.LOGIN_URL</literal>: URL to logging-in.</para></listitem> + <listitem><para><literal>org.jboss.portal.header.DASHBOARD_URL</literal>: URL to the dashboard, null if the user is already on the dashboard, null if the user is on the default portal already.</para></listitem> + <listitem><para><literal>org.jboss.portal.header.DEFAULT_PORTAL_URL</literal>: URL to the default page of the portal named 'default', null if the user is on the default portal already.</para></listitem> + <listitem><para><literal>org.jboss.portal.header.ADMIN_PORTAL_URL</literal>: URL to the default page of the admin portal (named 'admin'), null if the user is on the admin portal already.</para></listitem> + <listitem><para><literal>org.jboss.portal.header.EDIT_DASHBOARD_URL</literal>: URL to the page content editor of the dashboard, set only if the user is on the dashboard, null otherwise.</para></listitem> + <listitem><para><literal>org.jboss.portal.header.COPY_TO_DASHBOARD_URL</literal>: URL to copy a page from a portal to the personal dashboard, null if the user is on the dashboard.</para></listitem> + <listitem><para><literal>org.jboss.portal.header.SIGN_OUT_URL</literal>: URL to log out the portal.</para></listitem> + </itemizedlist> + Every attribute that is an URL attribute is an object implementing the <emphasis>org.jboss.portal.api.PortalURL</emphasis> interface. + Therefore it is possible to generate the URL using the <emphasis>toString()</emphasis> method and change various things related + to the URL. + With that in hand, if someone just wanted to display the logged-in username and a link to log out, he could write: + <programlisting><![CDATA[<%@ page import="org.jboss.portal.identity.User" %> + +<% + User user = (User) request.getAttribute("org.jboss.portal.header.USER"); + PortalURL signOutURL = (PortalURL)request.getAttribute("org.jboss.portal.header.SIGN_OUT_URL"); + PortalURL loginURL = (PortalURL)request.getAttribute("org.jboss.portal.header.LOGIN_URL"); + + + if (user == null) + { +%> + <a href="<%= loginURL %>">Login</a> +<% + } + else + { +%> +Logged in as: <%= user.getUserName() %> +<br/> +<a href="<%= signOutURL %>">Logout</a> +<% + } +%>]]></programlisting> + </para> + <para>Writing the tabs JSP</para> + <para>A couple of request attributes are set so that they can be used by the JSP, here is the list of attributes and their meaning: + <itemizedlist> + <listitem><para><literal>org.jboss.portal.api.PORTAL_NODE</literal>: A <literal>org.jboss.portal.api.node.PortalNode</literal> object of the root Portal node. Authorized children and siblings + of this object are accessible.</para></listitem> + <listitem><para><literal>org.jboss.portal.api.PORTAL_RUNTIME_CONTEXT</literal>: A <literal>org.jboss.portal.api.PortalRuntimeContext</literal> object that can be used to render URLs.</para></listitem> + </itemizedlist> + </para> + <para>The default file in charge of displaying the tabs can be found in: <literal>portal-core.war/WEB-INF/jsp/header/</literal></para> + </section> + <!-- section> + <title>Modifying the default PageCustomizerInterceptor</title> + <para>Instead of modifying the class directly, create your own Interceptor + (I suggest you copy the default PageCustomizerInterceptor look at the source in + <literal>core/src/main/org/jboss/portal/core/aspects/controller</literal>) then add it to: + <literal>portal-core.sar/META-INF/jboss-service.xml</literal> the same way it + is done by the default Interceptor. Then replace the default one by your own in + the following part: +<programlisting><![CDATA[ +<mbean + code="org.jboss.portal.server.impl.invocation.JBossInterceptorStackFactory" + name="portal:service=InterceptorStackFactory,type=Command" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <depends-list optional-attribute-name="InterceptorNames"> + <depends-list-element>portal:service=Interceptor,type=Command,name=Ajax</depends-list-element> + <depends-list-element>portal:service=Interceptor,type=Command,name=NavigationalState</depends-list-element> + <depends-list-element>portal:service=Interceptor,type=Command,name=PortalNode</depends-list-element> + <depends-list-element>portal:service=Interceptor,type=Command,name=PolicyEnforcement</depends-list-element> + <depends-list-element>portal:service=Interceptor,type=Command,name=PageCustomizer</depends-list-element> + <depends-list-element>portal:service=Interceptor,type=Command,name=EventBroadcaster</depends-list-element> + </depends-list> +</mbean> +]]></programlisting> + Just replace the PageCustomizer by one of your own. + </para> + </section--> + </section> + </section> + <section id="layouts"> + <title>Layouts</title> + <section> + <title>How to define a Layout</title> + <para>Layouts are used by the portal to produce the actual markup of a portal response. + After all the portlets on a page have been rendered and have produced their markup + fragments, the layout is responsible for aggregating all these pieces, mix them with + some ingredients from the portal itself, and at the end write the response back to the + requesting client. + </para> + <para>Layouts can be either a JSP or a Servlet. The portal determines the layout to use + via the configured properties of the portal, or the requested page. Both, portal and + pages, can define the layout to use in order to render their content. In case both + define a layout, the layout defined for the page will overwrite the one defined for the + portal. + </para> + <para>A Layout is defined in the layout descriptor named portal-layouts.xml. This + descriptor must be part of the portal application, and is picked up by the layout + deployer. If the layout deployer detects such a descriptor in a web application, it will + parse the content and register the layouts with the layout service of the portal. Here + is an example of such a descriptor file: + <programlisting><![CDATA[<layouts> + <layout> + <name>phalanx</name> + <uri>/phalanx/index.jsp</uri> + </layout> + <layout> + <name>industrial</name> + <uri>/industrial/index.jsp</uri> + <uri state="maximized">/industrial/maximized.jsp</uri> + </layout> +</layouts>]]></programlisting> + </para> + </section> + <section> + <title>How to use a Layout</title> + <section> + <title>Declarative use</title> + <para>Portals and pages can be configured to use a particular layout. The connection to + the desired layout is made in the portal descriptor (YourNameHere-object.xml). Here + is an example of such a portal descriptor: + <programlisting><![CDATA[<portal> + <portal-name>default</portal-name> + <properties> + <!-- Set the layout for the default portal --> + <!-- see also portal-layouts.xml --> + <property> + <name>layout.id</name> + <value>phalanx</value> + </property> + </properties> + <pages> + <page> + <page-name>theme test</page-name> + <properties> + <!-- set a difference layout for this page --> + <property> + <name>layout.id</name> + <value>industrial</value> + </property> + </properties> + </page> + </pages> +</portal>]]></programlisting> + The name specified for the layout to use has to + match one of the names defined in the portal-layouts.xml descriptor of one of the + deployed applications. + </para> + <para>As you can see, the portal or page property points to the layout to use via the + name of the layout. The name has been given to the layout in the layout descriptor. + It is in that layout descriptor where the name gets linked to the physical resource + (the JSP or Servlet) that will actually render the layout. + </para> + </section> + <section> + <title>Programmatic use</title> + <para>To access a layout from code, you need to get a reference to the LayoutService + interface. The layout service is an mbean that allows access to the PortalLayout + interface for each layout that was defined in a portal layout descriptor. As a layout + developer you should never have to deal with the layout service directly. Your layout + hooks are the portal and page properties to configure the layout, and the layout + strategy, where you can change the layout to use for the current request, before the + actual render process begins. + </para> + </section> + </section> + <section> + <title>Where to place the Descriptor files</title> + <para>Both descriptors, the portal and the theme descriptor, are located in the WEB-INF/ + folder of the deployed portal application. Note that this is not limited to the + portal-core.war, but can be added to any WAR that you deploy to the same server. The + Portal runtime will detect the deployed application and introspect the WEB-INF folder + for known descriptors like the two mentioned here. If present, the appropriate meta data + is formed and added to the portal runtime. From that time on the resources in that + application are available to be used by the portal. This is an elegant way to + dynamically add new layouts or themes to the portal without having to bring down , or + even rebuild the core portal itself. + </para> + </section> + <!-- + <section> + <title>How to connect a Layout to a Layout Strategy</title> + <para>As you might have noticed already, a layout definition consists of a name and one or + more uri elements. We have already seen the function of the name element. Now let's take + a closer look at the uri element. In the example above, the phalanx layout defined one + uri element only, the industrial layout defines two. What you can see in the industrial + layout is the option of defining different uri's for different states. In this example , + we configured the layout to use a different JSP if the layout state is maximized. If no + such separation is made in the layout descriptor, then the portal will always use the + same JSP for this layout. Note that the 'state' attribute value works together with the + state that was set by the layout strategy. Please refere to the section about the layout + strategy for more details. + </para> + </section> + --> + <section> + <title>Layout <trademark class="trade">JSP</trademark> tags</title> + <para>The portal comes with a set of <trademark class="trade">JSP</trademark> tags that allow the layout developer faster + development. + </para> + <para>There are currently two taglibs, containing tags for different approaches to + layouts: + </para> + <itemizedlist> + + <listitem><para>portal-layout.tld</para></listitem> + <listitem><para>theme-basic-lib.tld</para></listitem> + </itemizedlist> + + <para>The theme-basic-lib.tld contains a list of tags that allow a JSP writer to access + the state of the rendered page content. It is built on the assumption that regions, + portlet windows and portlet decoration is managed inside the JSP. + </para> + <para>The portal-layout.tld contains tags that work under the assumption that the + RenderSet will take care of how regions, portlet windows and the portlet decoration will + be rendered. The advantage of this approach is that the resulting JSP is much simpler + and easier to read and maintain. + </para> + <para>Here is an example layout JSP that uses tags from the latter: + <programlisting> + <![CDATA[<%@ taglib uri="/WEB-INF/theme/portal-layout.tld" prefix="p" %> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title><p:title default="My Great Portal"/></title> + <meta http-equiv="Content-Type" content="text/html;" /> + <p:theme themeName='renaissance' /> + <p:headerContent /> + </head> + <body id="body"> + <div id="portal-container"> + <div id="sizer"> + <div id="expander"> + <div id="logoName"></div> + <table border="0" cellpadding="0" cellspacing="0" id="header-container"> + <tr> + <td align="center" valign="top" id="header"> + <div id="spacer"></div> + </td> + </tr> + </table> + <div id="content-container"> + <p:region regionName='This-Is-The-Page-Region-To-Query-The-Page' + regionID='This-Is-The-Tag-ID-Attribute-To-Match-The-CSS-Selector'/> + <p:region regionName='left' regionID='regionA'/> + <p:region regionName='center' regionID='regionB'/> + <hr class="cleaner" /> + <div id="footer-container" class="portal-copyright">Powered by + <a class="portal-copyright" + href="http://www.jboss.com/products/jbossportal"> + JBoss Portal + </a> + </div> + </div> + </div> + </div> + </div> + </body> +</html>]]></programlisting> + </para> + <section> + <title>The title tag</title> + <para>The title tag is used to insert the web browser title defined by a portlet which + is part of the page rendering. The default attribute defines the title to use if no + portlet defined a web browser title. + </para> + </section> + <section> + <title>The theme tag</title> + <para>The theme tag looks for the determined theme of the current request (see + Portal Themes for more details). If no theme was determined, this tag allows an + optional attribute 'themeName' that can be used to specify a default theme to use + as a last resort. Based on the determined theme name, the ThemeService is called + to lookup the theme with this name and to get the resources associated with this + theme. The resulting style and link elements are injected, making sure that war + context URLS are resolved appropriately. + </para> + </section> + <section> + <title>The headerContent tag</title> + <para>This tags allows portlets to inject content into the header. More details + about this function are mentioned in the 'other Theme Functions' section of this + document. + </para> + </section> + <section> + <title>The region tag</title> + <para>The region tag renders all the portlets in the specified region of the current + page, using the determined RenderSet to produce the markup that surrounds the + individual portlet markup fragments. The regionName attribute functions as a query + param into the current page. It determines from what page region the portlets will + be rendered in this tag. The regionID attribute is what the RenderSet can use to + generate a CSS selector for this particular region. In case of the divRenderer, a + DIV tag with an id attribute corresponding to the provided value will be rendered + for this region. This id in turn can be picked up by the CSS to style the region. + </para> + </section> + </section> + </section> + <!-- +<section> +<title>Layout Strategy</title> +<section> +<title>What is a Layout Strategy</title> +<para>The layout strategy is a pluggable API that allows the layout developer to influence +the content of the page that is about to be rendered. Based on the current request URL, +the portal determined the portal and page that needs to be rendered. The page contains a +list of portlets, and those portlets are in a particular navigational state. The +navigational state consists of the portlet mode and the window state of the portlet. +This information, togeher with the determined layout, the region and order assignments +of each portlet, the allowed window states and portlet modes for both, the portal and +the individual portlets, is passed to the layout strategy before the actual rendering is +invoked. The layout strategy can check what is about to be rendered, and take action in +a limited way to influence the content that is about to be rendered. +</para> +</section> +<section> +<title>How can I use a Layout Strategy</title> +<section> +<title>Define a Strategy</title> +<para>A layout strategy is defined in the strategy descriptor. The descriptor is named + portal-strategies.xml, and is located in the WEB-INF/layout folder of any web + application deployed to the server. Here is an example of such a descriptor: + <programlisting> + <![CDATA[<portal-strategies> + <set name="default"> + <strategy content-type="text/html"> + <implementation>org.jboss.portal.theme.impl.strategy.DefaultStrategyImpl</implementation> + </strategy> + </set> + <set name="maximizedRegion"> + <strategy content-type="text/html"> + <implementation>org.jboss.portal.theme.impl.strategy.MaximizingStrategyImpl</implementation> + </strategy> + </set> + </portal-strategies> + ]]></programlisting> + Layout strategies are defined as sets. A set consists of one or + more strategy definitions, separated by content type they are assigned for. The idea + behind this is to allow the layout developer to apply different strategies based on + requested content type. Each set has a name that is unique in the application context + it is deployed in. The strategy can be refered to by this name. As a result of that + it is considered a named layout strategy in contrast to an anonymous strategy as + described below. +</para> +</section> +<section> +<title>Specify the Strategy to use</title> +<para>The strategy that will be used for a portal request is defined as a property of + the current layout, the requested portal, or the requested page. If the layout + defines a strategy to use it will overwrite all other assignments. If there is no + particular strategy defined for the layout, then the page property will overwrite the + portal property. If no strategy can be determined, then a last attempt will be made + to use the strategy with the name 'default'. If no strategy can be determined at all, + the request will proceed normally without invoking any strategy. Here is an example + layout descriptor that defines a strategy for the layouts defined: + <programlisting> + <![CDATA[ + <layouts> + <strategy content-type="text/html"> + <implementation>com.novell.portal.strategy.MaximizingStrategy</implementation> + </strategy> + + <layout> + <name>generic</name> + <uri>/generic/index.jsp</uri> + <uri state="maximized">/generic/maximized.jsp</uri> + </layout> + </layouts> + ]]></programlisting> + In this case the strategy is anonymous and directly assigned to + the generic layout. The strategy cannot be discovered independently from the generic + layout. Here is an example portal descriptor that points to a strategy for the + portal, and for a particular page: + <programlisting> + <![CDATA[ + <portal> + <portal-name>default</portal-name> + <properties> + <property> + <name>layout.strategyId</name> + <value>default</value> + </property> + </properties> + <pages> + <default-page>theme test</default-page> + <page> + <page-name>theme test</page-name> + <properties> + --> + <!-- set a difference layout strategy for this page --> + <!-- + <property> + <name>layout.strategyId</name> + <value>maximizedRegion</value> + </property> + </properties> + <window> + <window-name>CatalogPortletWindow</window-name> + <instance-ref>CatalogPortletInstance</instance-ref> + <region>left</region> + <height>0</height> + </window> + </page> + </pages> + </portal> + ]]></programlisting> + As you can see, analogous to how layouts are refered to, the + strategy name is the linking element between the portal descriptor and the layout + strategy descriptor. The content type is determined at runtime, and serves as a + secondary query parameter to get the correct strategy for this content type out of + the set that matches the name provided in the portal descriptor. + </para> + </section> + </section> + <section> + <title>Linking the Strategy and the Layout</title> + <para>As mentioned above, the layout descriptor can link a strategy directly to the + layout. This will overwrite all other defined strategies for the portal or the page, for + any page that uses this layout. + </para> + <para>The layout strategy can set a state to return to the portal as a result of the + strategy evaluation. This state will be matched with the state attribute of the uri + element of the layout. If there is a match, then the uri that matches this state will be + used as the layout for the current request. So, if the strategy sets a state of + 'maximized' , the portal will try to use the layout resource that is pointed to for that + particular state in the currently selected layout. As you might remember from the + previous layout section, a layout can point to another JSP or Servlet based on the state + attribute of the uri element, like so: + <programlisting><![CDATA[ + <layouts> + <layout> + <name>industrial</name> + <uri>/industrial/index.jsp</uri> + <uri state="maximized">/industrial/maximized.jsp</uri> + </layout> + </layouts>]]></programlisting> + In this case all reuquests that don't return a state + 'maximized' from the evaluation of the strategy will use the /industrial/index.jsp as + the layout. However, if the evaluation of the strategy returns a state of 'maximized' + then the request will use /industrial/maximized.jsp as the layout. + </para> + </section> + </section> + --> + <section> + <title>RenderSets</title> + <section> + <title>What is a RenderSet</title> + <para>A RenderSet can be used to produce the markup containers around portlets and portlet + regions. The markup for each region, and each portlet window in a region is identical. + Further more, it is most likely identical across several layouts. The way portlets are + arranged and decorated will most likely not change across layouts. What will change is + the look and feel of the decoration, the images, fonts, and colors used to render each + portlet window on the page. This is clearly a task for the web designer, and hence + should be realized via the portal theme. The layout only needs to provide enough + information to the theme so that it can do its job. The RenderSet is exactly that link + between the layout and the theme that takes the information available in the portal and + renders markup containing the current state of the page and each portlet on it. It makes + sure that the markup around each region and portlet contains the selectors that the + theme CSS needs to style the page content appropriately. + </para> + <para>A RenderSet consists of the implementations of four interfaces. Each of those + interfaces corresponds to a markup container on the page. + </para> + <para>Here are the four markup containers and their interface representation:</para> + <itemizedlist> + + <listitem><para>Region - RegionRenderer</para></listitem> + <listitem><para>Window - WindowRenderer</para></listitem> + <listitem><para>Decoration - DecorationRenderer</para></listitem> + <listitem><para>Portlet Content - PortletRenderer</para></listitem> + </itemizedlist> + <para> + All the renderer interfaces are specified in the + org.jboss.portal.theme.render package. + </para> + <para>The four markup containers are hierarchical. The region contains one or more + windows. A window contains the portlet decoration and the portlet content. + </para> + <para>The region is responsible for arranging the positioning and order of each portlet + window. Should they be arranged in a row or a column? If there are more then one portlet + window in a region, in what order should they appear? + </para> + <para>The window is responsible for placing the window decoration, including the portlet + title, over the portlet content, or under, or next to it. + </para> + <para>The decoration is responsible for inserting the correct markup with the links to the + portlet modes and window states currently available for each portlet. + </para> + <para>The portlet content is responsible for inserting the actually rendered markup + fragment that was produced by the portlet itself. + </para> + </section> + <section> + <title>How is a RenderSet defined</title> + <para>Similar to layouts, render sets must be defined in a RenderSet descriptor. The + RenderSet descriptor is located in the WEB-INF/layout folder of a web application, and + is named portal-renderSet.xml. Here is an example descriptor: + <programlisting> + <![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<portal-renderSet> + <renderSet name="divRenderer"> + <set content-type="text/html"> + <region-renderer>org.jboss.portal.theme.impl.render.DivRegionRenderer</region-renderer> + <window-renderer>org.jboss.portal.theme.impl.render.DivWindowRenderer</window-renderer> + <portlet-renderer>org.jboss.portal.theme.impl.render.DivPortletRenderer</portlet-renderer> + <decoration-renderer> + org.jboss.portal.theme.impl.render.DivDecorationRenderer + </decoration-renderer> + </set> + </renderSet> + <renderSet name="emptyRenderer"> + <set content-type="text/html"> + <region-renderer>org.jboss.portal.theme.impl.render.EmptyRegionRenderer</region-renderer> + <window-renderer>org.jboss.portal.theme.impl.render.EmptyWindowRenderer</window-renderer> + <portlet-renderer> + org.jboss.portal.theme.impl.render.EmptyPortletRenderer + </portlet-renderer> + <decoration-renderer> + org.jboss.portal.theme.impl.render.EmptyDecorationRenderer + </decoration-renderer> + </set> + </renderSet> +</portal-renderSet> + ]]></programlisting> + </para> + </section> + <section> + <title>How to specify what RenderSet to use</title> + <para>Analogous to how a strategy is specified, the RenderSet can be specified as a portal + or page property, or a particular layout can specify an anonymous RenderSet to use. Here + is an example of a portal descriptor: + <programlisting> + <![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<portal> + <portal-name>default</portal-name> + <properties> + <!-- use the divRenderer for this portal --> + <property> + <name>theme.renderSetId</name> + <value>divRenderer</value> + </property> + </properties> + <pages> + <default-page>default</default-page> + <page> + <page-name>default</page-name> + <properties> + <!-- overwrite the portal's renderset for this page --> + <property> + <name>theme.renderSetId</name> + <value>emptyRenderer</value> + </property> + </properties> + <window> + <window-name>TestPortletWindow</window-name> + <instance-ref>TestPortletInstance</instance-ref> + <region>center</region> + <height>0</height> + </window> + </page> + </pages> +</portal>]]></programlisting> + Here is an example of a layout descriptor with an anonymous + RenderSet: + <programlisting> + <![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<layouts> +<renderSet> +<set content-type="text/html"> +<region-renderer>org.foo.theme.render.MyRegionRenderer</region-renderer> +<window-renderer>org.foo.theme.render.MyWindowRenderer</window-renderer> +<portlet-renderer>org.foo.theme.render.MyPortletRenderer</portlet-renderer> +<decoration-renderer>org.foo.theme.render.MyDecorationRenderer</decoration-renderer> +</set> +</renderSet> +<layout> +<name>generic</name> +<uri>/generic/index.jsp</uri> +<uri state="maximized">/generic/maximized.jsp</uri> +</layout> +</layouts>]]></programlisting> + Again, analogous to layout strategies, the anonymous RenderSet + overwrites the one specified for the page, and that overwrites the one specified for the + portal. In other words: all pages that use the layout that defines an anonymous + RenderSet will use that RenderSet, and ignore what is defined as RenderSet for the + portal or the page. + </para> + <para> + In addition to specifying the renderSet for a portal or a page, each individual portlet window + can define what renderSet to use for the one of the three aspects of a window, the window renderer, + the decoration renderer, and the portlet renderer. This feature allow you to use the the window renderer + implementation from one renderSet, and the decoration renderer from another. + Here is an example for a window that uses the implementations of the emptyRenderer renderSet for all three + aspects: + <programlisting> + <![CDATA[<window> + <window-name>NavigationPortletWindow</window-name> + <instance-ref>NavigationPortletInstance</instance-ref> + <region>navigation</region> + <height>0</height> + <!-- overwrite portal and page properties set for the renderSet for this window --> + <properties> + <!-- use the window renderer from the emptyRenderer renderSet --> + <property> + <name>theme.windowRendererId</name> + <value>emptyRenderer</value> + </property> + <!-- use the decoration renderer from the emptyRenderer renderSet --> + <property> + <name>theme.decorationRendererId</name> + <value>emptyRenderer</value> + </property> + <!-- use the portlet renderer from the emptyRenderer renderSet --> + <property> + <name>theme.portletRendererId</name> + <value>emptyRenderer</value> + </property> + </properties> +</window>]]></programlisting> + + </para> + </section> + </section> + <section> + <title>Themes</title> + <section> + <title>What is a Theme</title> + <para>A portal theme is a collection of CSS styles, JavaScript files, and images, that all + work together to style and enhance the rendered markup of the portal page. The theme + works together with the layout and the RenderSet in producing the content and final look + and feel of the portal response. Through clean separation of markup and styles a much + more flexible and powerful approach to theming portals is possible. While this approach + is not enforced, it is strongly encouraged. If you follow the definitions of the + Theme Style Guide (see later), it is not necessary to change the layout or the strategy, + or the RenderSet to achieve very different look and feels for the portal. All you need + to change is the theme. Since the theme has no binary dependencies, it is very simple to + swap, or change individual items of it. No compile or redeploy is necessary. Themes + can be added or removed while the portal is active. Themes can be deployed in separate + web applications furthering even more the flexibility of this approach. Web developers + don't have to work with JSP pages. They can stay in their favorite design tool and simple + work against the exploded war content that is deployed into the portal. The results can + be validated life in the portal. + </para> + </section> + <section> + <title>How to define a Theme</title> + <para>Themes can be added as part of any web application that is deployed to the portal + server. All what is needed is a theme descriptor file that is part of the deployed + archive. This descriptor indicates to the portal what themes and theme resources are + becoming available to the portal. The theme deployer scans the descriptor and adds the + theme(s) to the ThemeService, which in turn makes the themes available for consumption + by the portal. Here is an example of a theme descriptor: + <programlisting> + <![CDATA[<themes> +<theme> +<name>nodesk</name> +<link href="/nodesk/css/portal_style.css" rel="stylesheet" type="text/css" /> +<link rel="shortcut icon" href="/images/favicon.ico" /> +</theme> +<theme> +<name>phalanx</name> +<link href="/phalanx/css/portal_style.css" rel="stylesheet" type="text/css" /> +<link rel="shortcut icon" href="/images/favicon.ico" /> +</theme> + +<theme> +<name>industrial-CSSSelect</name> +<link rel="stylesheet" id="main_css" href="/industrial/portal_style.css" type="text/css" /> +<link rel="shortcut icon" href="/industrial/images/favicon.ico" /> + +<script language="JavaScript" type="text/javascript"> +// MAF - script to switch current tab and css in layout... +function switchCss(currentTab,colNum) { +var obj = currentTab; +var objParent = obj.parentNode; + +if (document.getElementById("current") != null) { +var o = document.getElementById("current"); +o.setAttribute("id",""); +o.className = 'hoverOff'; +objParent.setAttribute("id","current"); +} + +var css = document.getElementById("main_css"); +source = css.href; +if (colNum == "3Col") { +if (source.indexOf("portal_style.css" != -1)) { +source = source.replace("portal_style.css","portal_style_3Col.css"); +} +if (source.indexOf("portal_style_1Col.css" != -1)) { +source = source.replace("portal_style_1Col.css","portal_style_3Col.css"); +} +} +if (colNum == "2Col") { +if (source.indexOf("portal_style_3Col.css" != -1)) { +source = source.replace("portal_style_3Col.css","portal_style.css"); +} +if (source.indexOf("portal_style_1Col.css" != -1)) { +source = source.replace("portal_style_1Col.css","portal_style.css"); +} +} +if (colNum == "1Col") { +if (source.indexOf("portal_style_3Col.css" != -1)) { +source = source.replace("portal_style_3Col.css","portal_style_1Col.css"); +} +if (source.indexOf("portal_style.css" != -1)) { +source = source.replace("portal_style.css","portal_style_1Col.css"); +} +} + +css.href = source; +} +</script> +</theme> +</themes>]]></programlisting> + </para> + <para>Themes are defined in the portal-themes.xml theme descriptor, which is located in + the WEB-INF/ folder of the web application. + </para> + </section> + <section> + <title>How to use a Theme</title> + <para>Again, analogous to the way it is done for layouts, themes are specified in the + portal descriptor as a portal or page property. The page property overwrites the portal + property. In addition to these two options, themes can also be specified as part of the + theme JSP tag , that is placed on the layout JSP. Here is an example portal descriptor + that specifies the phalanx theme as the theme for the entire portal, and the industrial + theme for the theme test page: + <programlisting> + <![CDATA[<portal> + <portal-name>default</portal-name> + <properties> + <!-- Set the theme for the default portal --> + <property> + <name>layout.id</name> + <value>phalanx</value> + </property> + </properties> + <pages> + <page> + <page-name>theme test</page-name> + <properties> + <!-- set a difference layout for this page --> + <property> + <name>layout.id</name> + <value>industrial</value> + </property> + </properties> + <window> + <window-name>CatalogPortletWindow</window-name> + <instance-ref>CatalogPortletInstance</instance-ref> + <region>left</region> + <height>0</height> + </window> + </page> + </pages> +</portal>]]></programlisting> + And here is an example of a layout JSP that defines a default + theme to use if no other theme was defined for the portal or page: + <programlisting> + <![CDATA[<%@ taglib uri="/WEB-INF/theme/portal-layout.tld" prefix="p" %> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title><%= "JBoss Portal :: 2.2 early (Industrial)" %></title> + <meta http-equiv="Content-Type" content="text/html;" /> + <p:theme themeName='industrial' /> + <p:headerContent /> + </head> + <body id="body"> + <div id="portal-container"> + <div id="sizer"> + <div id="expander"> + <div id="logoName"></div> + <table border="0" cellpadding="0" cellspacing="0" + id="header-container"> + <tr> + <td align="center" valign="top" id="header"> + <div id="spacer"></div> + </td> + </tr> + </table> + <div id="content-container"> + <p:region + regionName='This-Is-The-Page-Region-To-Query-The-Page' + regionID='This-Is-The-Tag-ID-Attribute-To-Match-The-CSS-Selector' /> + <p:region regionName='left' regionID='regionA' /> + <p:region regionName='center' regionID='regionB' /> + <hr class="cleaner" /> + <div id="footer-container" class="portal-copyright"> + Powered by + <a class="portal-copyright" + href="http://www.jboss.com/products/jbossportal"> + JBoss Portal + </a> + <br /> + Theme by + <a class="portal-copyright" + href="http://www.novell.com"> + Novell + </a> + </div> + </div> + </div> + </div> + </div> + </body> +</html>]]></programlisting> + For the function of the individual tags in this example, please + refer to the layout section of this document. + </para> + </section> + <section> + <title>How to write your own Theme</title> + <para>Ask your favorite web designer and/or consult the Theme Style Guide in this document.</para> + </section> + </section> + <section> + <title>Other Theme Functionalities and Features</title> + <para>This section contains all the functionalities that don't fit with any of the other + topics. Bits and pieces of useful functions that are related to the theme and layout + functionality. + </para> + <section> + <title>Content Rewriting and Header Content Injection</title> + <para>Portlets can have their content rewritten by the portal. This is useful if you want + to uniquely namespace markup (JavaScript functions for example) in the scope of a page. + The rewrite functionality can be applied to the portlet content (the markup fragment) + and to content a portlet wants to inject into the header. The rewrite is implemented as + specified in the WSRP (OASIS: Web Services for Remote Portlets; producer write). As a + result of this, the token to use for rewrite is the WSRP specified "wsrp_rewrite_". If + the portlet sets the following response property + <programlisting>res.setProperty("WSRP_REWRITE","true");</programlisting> + all occurrences + of the wsrp_rewrite_ token in the portlet fragment will be replaced with a unique token + (the window id). If the portlet also specifies content to be injected into the header of + the page, that content is also subject to this rewrite. + <programlisting><![CDATA[res.setProperty("HEADER_CONTENT", " + <script>function wsrp_rewrite_OnFocus(){alert('hello button');}</script> + ");]]> + </programlisting> + Note that in order for the header content injection to work, the layout needs to make + use of the headerContent JSP tag, like: + <programlisting> + <![CDATA[<%@ taglib uri="/WEB-INF/theme/portal-layout.tld" prefix="p" %> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title><JBoss Portal 2.2 early</title> + <meta http-equiv="Content-Type" content="text/html;" /> + + <p:headerContent /> + </head> + <body id="body"> + <p>...</p> + </body> +</html>]]></programlisting> + </para> + </section> + <section> + <title>Declarative CSS Style injection</title> + <para>If a portlet needs a CSS style sheet to be injected via a link tag in the page + header, it can do so by providing the context relative URI to the file in the + jboss-portlet.xml descriptor, like: + <programlisting> + <![CDATA[<portlet-app> + <portlet> + <portlet-name>HeaderContentPortlet</portlet-name> + <header-content> + <link rel="stylesheet" type="text/css" href="/portlet-styles/HeaderContent.css" + title="" media="screen" /> + </header-content> + </portlet> +</portlet-app>]]></programlisting> + </para> + <para>This functionality, just like the previously described header content injection, + requires the layout JSP to add the "headerContent" JSP tag (see example above). One thing to note here is + the order of the tags. If the headerContent tag is placed after the theme tag, it will allow portlet + injected + CSS files to overwrite the theme's behavior, making this feature even more powerful! + </para> + </section> + <section> + <title>Disabling Portlet Decoration</title> + <para>One possible use of window properties is demonstrated in the divRenderer RenderSet implementation. + If a window definition (in the portal descriptor) contains a property like: + <programlisting> + <![CDATA[<window> + <window-name>HintPortletWindow</window-name> + <instance-ref>HintPortletInstance</instance-ref> + <region>center</region> + <height>0</height> + <properties> + <!-- turn the decoration off for this portlet (i.e. no title and mode/state links) --> + <property> + <name>theme.decorationRendererId</name> + <value>emptyRenderer</value> + </property> + </properties> +</window>]]></programlisting> + the DivWindowRenderer will use the decoration renderer from the emptyRenderer + RenderSet to render the decoration for this window (not delegate to the DivDecorationRenderer). + As a result, the portlet window will be part of the rendered page, but it will not have a title, + nor will it have any links to change the portlet mode or window state. + </para> + </section> + </section> + <section> + <title>Theme Style Guide (based on the Industrial theme)</title> + <section> + <title>Overview</title> + <note><title>Note</title><para>This section to be updated soon with new CSS selectors found in JBoss Portal 2.6. The current + definitions remain, but the newer additions with regards to dashboards/drag-n-drop have not been + documented as of yet.</para> + </note> + <para>This document outlines the different selectors used to handle the layout and + look/feel of the Industrial theme included in the JBoss portal. + </para> + <para>A couple of things to know about the theming approach discussed below:</para> + + <itemizedlist> + + <listitem><para>Main premise behind this approach was to provide a clean separation between + the business and presentation layer of the portal. As we go through each selector + and explain the relation to the visual presentation on the page, this will become + more apparent.</para> + </listitem> + <listitem><para>The flexibility of the selectors used in the theme stylesheet allow a + designer to very easily customize the visual aspects of the portal, thereby taking + the responsibility off of the developers hands through allowing the designer to + quickly achieve the desired effect w/out the need to dive down into code and/or + having to deploy changes to the portal. This saves time and allows both developers + and designers to focus on what they do best.</para> + </listitem> + <listitem><para>This theme incorporates a liquid layout approach which allows elements on a + page to expand/contract based on screen resolution and provides a consistent look + across varying display settings. However, the stylesheet is adaptable to + facilitate a fixed layout and/or combination approach where elements are pixel + based and completely independent of viewport.</para> + </listitem> + <listitem><para>The pieces that make up the portal theme consist of at least one stylesheet + and any associated images. Having a consolidated set of files to control the + portal look and feel allows administrators to effortlessly swap themes on the fly. + In addition, this clean separation of the pieces that make up a specific theme + will enable sharing and collaboration of different themes by those looking to get + involved or contribute to the open source initiative.</para> + </listitem> + </itemizedlist> + + </section> + <section> + <title>Main Screen Shot</title> + <para>Screen shot using color outline of main ID selectors used to control presentation + and layout: + <mediaobject> + <imageobject> + <imagedata fileref="images/themeguide/selector-outline.gif" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + + <itemizedlist> + <listitem><para>Red Border - portal-container</para></listitem> + <listitem><para>Yellow Border - header-container</para></listitem> + <listitem><para>Orange Border - content-container</para></listitem> + <listitem><para>Blue Border - regionA/regionB</para></listitem> + <listitem><para>Green Border - portlet-container</para></listitem> + </itemizedlist> + + </section> + <section> + <title>List of CSS Selectors</title> + + <para>The following is a list of the selectors used in the theme stylesheet, + including a brief explanation of how each selector is used in the portal: + </para> + <itemizedlist> + + <listitem> + <para>Portal Body Selector + <programlisting>#body { + background-color: #FFFFFF; + background-image: url( images/header_bg.gif ); + background-repeat: repeat-x; + margin: 0px; + padding: 0px; + font-family: Verdana, Arial, Helvetica, sans-serif; + background-repeat: repeat-x; + font-size: 11px; + color: #656565; +}</programlisting> + Usage: This selector controls the background of the page, and can be modified + to set a base font-family, layout margin, etc. that will be inherited by all + child elements that do not have their own individual style applied. By default, + the selector pulls an image background for the page. + </para> + </listitem> + <listitem> + <para>Portal Header Selectors + <programlisting>#spacer { + width: 770px; + line-height: 0px; + font-size: 0px; + height: 0px; +}</programlisting> + Usage: Spacer div used to keep header at certain width regardless of display + size. This is done to avoid overlapping of tab navigation in header. To account + for different display sizes, this selector can be modified to force a + horizontal scroll in the browser which eliminates any issue with overlapping + elements in the header. + <programlisting>#header-container { + background-repeat: repeat-y; + height: 100%; + min-width: 1000px; + width: 100%; + position: absolute; + bottom: 5px;*/ + }</programlisting> + Usage: Wrapper selector used to control the position of the header on the page. + This selector is applied as an ID on the + table used to structure the header. You can adjust the attributes to reposition + the header location on the page and/or create margin space on the top, right, + bottom and left sides of the header. + Screenshot: + + <mediaobject> + <imageobject> + <imagedata fileref="images/themeguide/portal-header.gif" scalefit="1"/> + </imageobject> + </mediaobject> + + <programlisting>#header { + height: 65px; + width: 100%; + padding: 0px; + margin: 0px; + z-index: 1; +}</programlisting> + Usage: This selector applies the header background image in the portal. It can + be adjusted to accommodate a header background of a certain width/height or, as + it currently does, repeat the header graphic so that it tiles across the header + portion of the page. + <programlisting>#logoName { + background-image: url( images/logo.gif ); + background-repeat: no-repeat; + float: left; + width: 250px; + height: 25px; + z-index: 2; + position: absolute; + left: 20px; + top: 10px; +}</programlisting> + Usage: Logo selector which is used to brand the header with a specific, + customized logo. The style is applied as an ID on an absolutely positioned DIV + element which enables it to be moved to any location on the page, and allows it + to be adjusted to accommodate a logo of any set width/height. + </para> + </listitem> + <listitem> + <para>Portal Layout Region Selectors + <programlisting>#portal-container { +/* part of below IE hack to preserve min-width for portlet regions */ +/*width: 100%;*/ + margin: 4px 2% 0px 2%; + + padding: 0 350px 0 350px; +}</programlisting> + Usage: Wrapper for entire portal which starts/ends after/before the BODY tag + (see red border in screen shot). The padding attribute for this selector is + used to preserve a minimum width setting for the portlet regions (discussed + below). Similar to body selector, this style can modified to create margin or + padding space on the top, right, bottom and left sections of the page. It + provides the design capability to accommodate most layouts (e.g. a centered + look such as the phalanx theme where there is some spacing around the content + of the portal, or a full width look as illustrated in the Industrial theme). + Screenshot: + + <mediaobject> + <imageobject> + <imagedata fileref="images/themeguide/region-selectors.gif" scalefit="1"/> + </imageobject> + </mediaobject> + + <programlisting>/* min width for IE */ +#expander { + position: relative; + padding: 0 0 0 0; + + margin: 0 -350px 0 -350px; + min-width: 770px; + padding: 0 0 0 0; +} + +/* min width hack for IE */ +#sizer { + width: 100%; +} + +/* IE Hack \*/ +* html #portal-container, + * html #sizer, + * html #expander { + height: 0; +}</programlisting> + Usage: These selectors are used in conjunction with the above, + portal-container, selector to preserve a minimum width setting for the portlet + regions. This was implemented to maintain a consistent look across different + browsers. + <programlisting>#content-container { + height: 100%; + text-align: left; + width: 100%; + min-width: 770px; + /* + position: absolute; + top: 70px; + left: 0px; / * z-index: 1; * / + / * part of below IE hack +padding: 0 350px 0 350px; * / + padding: 0px 100px 0px 0px; + */ +}</programlisting> + Usage: Wrapper that contains all regions in portal with the exception of the + header (see orange border in screen shot). Its attributes can be adjusted to + create margin space on page, as well as control positioning of the area of the + page below the header. + <programlisting>/* portlet regions within content-container. this includes footer-container. */ +#regionA { + width: 30%; + float: left; + margin: 0px; + padding: 0px; + min-width: 250px; /*height: 300px;*/ +}</programlisting> + Usage: First portlet region located within the content-container (see blue + border in screen shot). This selector controls the width of the region as well + as its location on the page. Designers can very easily reposition this region + in the portal (e.g. swap left regionA with right regionB, etc.) by adjusting + the attributes of this selector. + <programlisting>#regionB { + /* test to swap columns.. +margin: 0 30% 0 0; */ + + /*two column layout +margin: 0 0 0 30%;*/ + padding: 0px; /* test to add 3rd region in layout...*/ + width: 67%; + float: left; /*height: 300px;*/ +}</programlisting> + Usage: Second portlet region located within the content-container (see blue + border in screen shot). Similar to regionA, this selector controls the width of + the region as well as its location on the page. + <programlisting>#regionC { +/* inclusion of 3rd region - comment out for 2 region testing */ + padding: 0px; + margin: 0px; + width: 28%; + float: left; /*hide 3rd region*/ + display: none; +}</programlisting> + Usage: Third portlet region located within the content-container (please refer + to blue border in screen shot representing regionA and regionB for an example). + Used for 3 column layout. Similar to regionA and regionB, this selector + controls the width of the region as well as its location on the page. + Screenshot: + + <mediaobject> + <imageobject> + <imagedata fileref="images/themeguide/regions.gif" scalefit="1"/> + </imageobject> + </mediaobject> + + <programlisting> +hr.cleaner { +clear:both; +height:1px; +margin: -1px 0 0 0; +padding:0; +border:none; +visibility: hidden; +} + </programlisting> + Usage: Used to clear floats in regionA, regionB and regionC DIVs so that footer + spans bottom of page. + <programlisting>#footer-container { + padding: 10px; + text-align: center; + clear: both; +}</programlisting> + Usage: Footer region located towards the bottom of the content-container (see + above screen shot). This region spans the entire width of the page, but can be + adjusted (just like regionA, regionB and regionC) to take on a certain position + and width/height in the layout. + </para> + </listitem> + <listitem> + <para>Portlet Container Window Selectors + <programlisting>.portlet-container { + padding: 10px; +}</programlisting> + Usage: Wrapper that surrounds the portlet windows (see green border in screen + shot). Currently, this selector is used to create space (padding) between the + portlets displayed in each particular region. + <programlisting>.portlet-titlebar-title { + color: #656565; + font-family: Verdana, Arial, Helvetica, sans-serif; + font-size: 12px; + font-weight: bold; + white-space: nowrap; + line-height: 100%; + float: left; + text-indent: 5px; + padding-top: 5px; + padding-bottom: 6px; +}</programlisting> + Usage: Class used to style the title of each portlet window. Attributes of this + selector set font properties, indentation and position of title. + <programlisting>.portlet-mode-container { + float: right; + padding-top: 4px; + white-space: nowrap; +}</programlisting> + Usage: Wrapper that contains the portlet window modes that display in the top + right section of the portlet windows. + <programlisting>.portlet-titlebar-left { + background-image: url( images/portlet-top-left.gif ); + background-repeat: no-repeat; + width: 9px; + height: 29px; + min-width: 9px; + background-position: bottom; +}</programlisting> + Usage: Used to style the top left corner of the portlet window. Each portlet + window consists of one table that has 3 columns and 3 rows. This selector + styles the first column (TD) in the first row (TR). + Screenshot: + <mediaobject> + <imageobject> + <imagedata fileref="images/themeguide/portlet-titlebar-left.gif"/> + </imageobject> + </mediaobject> + <programlisting>.portlet-titlebar-center { + background-image: url( images/portlet-top-middle.gif ); + background-repeat: repeat-x; + height: 29px; + background-position: bottom; +}</programlisting> + Usage: Used to style the center section of the portlet title bar. Each portlet + window consists of one table that has 3 columns and 3 rows. This selector + styles the second column (TD) in the first row (TR). + Screenshot: + <mediaobject> + <imageobject> + <imagedata fileref="images/themeguide/portlet-titlebar-center.gif"/> + </imageobject> + </mediaobject> + <programlisting>.portlet-titlebar-right { + background-image: url( images/portlet-top-right.gif ); + background-repeat: no-repeat; + width: 10px; + height: 30px; + min-width: 10px; + background-position: bottom left; +}</programlisting> + Usage: Used to style the top right corner of the portlet window. Each portlet + window consists of one table that has 3 columns and 3 rows. This selector + styles the third column (TD) in the first row (TR). + Screenshot: + <mediaobject> + <imageobject> + <imagedata fileref="images/themeguide/portlet-titlebar-right.gif"/> + </imageobject> + </mediaobject> + <programlisting>.portlet-content-left { + background-image: url( images/portlet-left-vertical.gif ); + background-repeat: repeat-y; + width: 9px; + min-width: 9px; + /* + width:20px; + background-color:#FFFFFF; + border-left: 1px solid #dfe8ed; + */ +}</programlisting> + Usage: Used to style the left hand vertical lines that make up the portlet + window. Each portlet window consists of one table that has 3 columns and 3 + rows. This selector styles the first column (TD) in the second row (TR). + + Screenshot: + + <mediaobject> + <imageobject> + <imagedata fileref="images/themeguide/portlet-content-left.gif"/> + </imageobject> + </mediaobject> + <programlisting>.portlet-content-center { + vertical-align: top; + padding: 0; + margin: 0; +}</programlisting> + Usage: Used to style the center, content area where the portlet content is + injected into the portlet window (see below screen). Attributes for this + selector control the positioning of the portlet content as well as the + background and font properties. Each portlet window consists of one table that + has 3 columns and 3 rows. This selector styles the second column (TD) in the + second row (TR). + Screenshot: + <mediaobject> + <imageobject> + <imagedata fileref="images/themeguide/portlet-content-center.gif"/> + </imageobject> + </mediaobject> + <programlisting>.portlet-body { + background-color: #FFFFFF; + padding: 0; + margin: 0; +}</programlisting> + Usage: An extra selector for controlling the content section of the portlet + windows (see below screen). This was added to better deal with structuring the + content that gets inserted/rendered in the portlet windows, specifically if the + content is causing display problems in a portlet. + Screenshot: + <mediaobject> + <imageobject> + <imagedata fileref="images/themeguide/portlet-body.gif"/> + </imageobject> + </mediaobject> + <programlisting>.portlet-content-right { + background-image: url( images/portlet-right-vertical.gif ); + height: 100%; + background-repeat: repeat-y; + background-position: left; + width: 5px; + min-width: 5px; + padding: 0; + margin: 0; + /* + width:5px; + background-color:#FFFFFF; + border-right: 1px solid #dfe8ed; + */ +}</programlisting> + Usage: Used to style the right hand vertical lines that make up the portlet + window. Each portlet window consists of one table that has 3 columns and 3 + rows. This selector styles the third column (TD) in the second row (TR). + + Screenshot: + + <mediaobject> + <imageobject> + <imagedata fileref="images/themeguide/portlet-content-right.gif"/> + </imageobject> + </mediaobject> + <programlisting>.portlet-footer-left { + background-image: url( images/portlet-bottom-left.gif ); + width: 9px; + height: 4px; + background-repeat: no-repeat; + background-position: top right; + min-width: 9px; + padding: 0; + margin: 0; + /* + background-color:#FFFFFF; + border-bottom: 1px solid #98b7c6; + border-left: 1px solid #dfe8ed; + height:5px; + */ +}</programlisting> + Usage: Used to style the bottom left corner of the portlet window. Each portlet + window consists of one table that has 3 columns and 3 rows. This selector + styles the first column (TD) in the third row (TR). + Screenshot: + <mediaobject> + <imageobject> + <imagedata fileref="images/themeguide/portlet-footer-left.gif"/> + </imageobject> + </mediaobject> + <programlisting>.portlet-footer-center { + background-image: url( images/portlet-bottom-middle.gif ); + height: 4px; + background-repeat: repeat-x; + /* background-color:#FFFFFF; + border-bottom: 1px solid #98b7c6; + height:5px; + */ +}</programlisting> + Usage: Used to style the bottom, center of the portlet window (i.e. the bottom + horizontal line in the Industrial theme). Each portlet window consists of one + table that has 3 columns and 3 rows. This selector styles the second column + (TD) in the third row (TR). + Screenshot: + <mediaobject> + <imageobject> + <imagedata fileref="images/themeguide/portlet-footer-center.gif"/> + </imageobject> + </mediaobject> + <programlisting>.portlet-footer-right { + background-image: url( images/portlet-bottom-right.gif ); + width: 5px; + height: 4px; + background-repeat: no-repeat; + min-width: 5px; + /* + background-color:#FFFFFF; + border-bottom: 1px solid #98b7c6; + border-right: 1px solid #dfe8ed; + height:5px; + */ +}</programlisting> + Usage: Used to style the bottom right corner of the portlet window. Each + portlet window consists of one table that has 3 columns and 3 rows. This + selector styles the third column (TD) in the third row (TR). + Screenshot: + <mediaobject> + <imageobject> + <imagedata fileref="images/themeguide/portlet-footer-right.gif"/> + </imageobject> + </mediaobject> + </para> + </listitem> + <listitem> + <para>Portlet Window Mode Selectors + <programlisting>.portlet-mode-maximized { + background-image: url( images/ico_16_maximize.gif ); + background-repeat: no-repeat; + width: 16px; + height: 16px; + float: left; + display: inline; + cursor: pointer; + padding-left: 3px; +}</programlisting> + Usage: Selector used to display the portlet maximize mode. Attributes for this + selector control the display and dimensions of the maximize icon, including the + behavior of the mouse pointer when hovering the mode. + <programlisting>.portlet-mode-minimized { + background-image: url( images/ico_16_minimize.gif ); + background-repeat: no-repeat; + width: 16px; + height: 16px; + float: left; + display: inline; + cursor: pointer; + padding-left: 3px; +}</programlisting> + Usage: Selector used to display the portlet minimize mode. Attributes for this + selector control the display and dimensions of the minimize icon, including the + behavior of the mouse pointer when hovering the mode. + <programlisting>.portlet-mode-normal { + background-image: url( images/ico_16_normal.gif ); + width: 16px; + height: 16px; + background-repeat: no-repeat; + float: left; + display: inline; + cursor: pointer; + padding-left: 3px; +}</programlisting> + Usage: Selector used to display the portlet normal mode (i.e. the icon that + when clicked, restores the portlet to the original, default view). Attributes + for this selector control the display and dimensions of the normal icon, + including the behavior of the mouse pointer when hovering the mode. + <programlisting>.portlet-mode-help { + background-image: url( images/ico_16_help.gif ); + width: 16px; + height: 16px; + background-repeat: no-repeat; + float: left; + display: inline; + cursor: pointer; + padding-left: 3px; +}</programlisting> + Usage: Selector used to display the portlet help mode. Attributes for this + selector control the display and dimensions of the help icon, including the + behavior of the mouse pointer when hovering the mode. + <programlisting>.portlet-mode-edit { + background-image: url( images/ico_edit.gif ); + background-repeat: no-repeat; + width: 28px; + height: 16px; + float: left; + display: inline; + cursor: pointer; + padding-left: 3px; +}</programlisting> + Usage: Selector used to display the portlet edit mode. Attributes for this + selector control the display and dimensions of the edit icon, including the + behavior of the mouse pointer when hovering the mode. + <programlisting>.portlet-mode-remove { + background-image: url( images/ico_16_remove.gif ); + background-repeat: no-repeat; + width: 16px; + height: 16px; + float: left; + display: inline; + cursor: pointer; + padding-left: 3px; +}</programlisting> + Usage: Currently not available. But here is the intended use: Selector used to + display the portlet remove mode. Attributes for this selector control the + display and dimensions of the remove icon, including the behavior of the mouse + pointer when hovering the mode. + <programlisting>.portlet-mode-view { + background-image: url( images/ico_cancel.gif ); + background-repeat: no-repeat; + width: 28px; + height: 16px; + float: left; + display: inline; + cursor: pointer; + padding-left: 3px; + padding-right: 20px; +}</programlisting> + Usage: Selector used to display the portlet view mode. Attributes for this + selector control the display and dimensions of the view icon, including the + behavior of the mouse pointer when hovering the mode. + <programlisting>.portlet-mode-reload { + background-image: url( images/ico_16_reload.gif ); + background-repeat: no-repeat; + width: 16px; + height: 16px; + float: left; + display: inline; + cursor: pointer; + padding-left: 3px; +}</programlisting> + Usage: Currently not available. But here is the intended use: Selector used to + display the portlet reload mode. Attributes for this selector control the + display and dimensions of the reload icon, including the behavior of the mouse + pointer when hovering the mode. + </para> + </listitem> + <listitem> + <para>Copyright Selectors + <programlisting>.portal-copyright { + font-family: Verdana, Arial, Helvetica, sans-serif; + font-size: 10px; + color: #5E6D7A; +} + +a.portal-copyright { + color: #768591; + text-decoration: none; +} + +a.portal-copyright:hover { + color: #bcbcbc; + text-decoration: underline; +}</programlisting> + Usage: The above three selectors are used to style copyright content in the + portal. The portal-copyright selector sets the font properties (color, etc.), + and the a.portal-copyright/a.portal-copyright:hover selectors style any links + that are part of the copyright information. + </para> + </listitem> + <listitem> + <para>Table Selectors + <programlisting>.portlet-table-header { + background-color: #eef; + padding: 0 5px 5px 5px; + font-weight: bold; + color: #656565; + font-size: 12px; + border-bottom: 1px solid #d5d5d5; +}</programlisting> + Usage: Intended for styling tables (specifically, the TH + or table header elements) that get rendered within a portlet window. + <programlisting>.portlet-table-body { + +}</programlisting> + Usage: Intended for styling the table body element used + to group rows in a table. + <programlisting>.portlet-table-alternate { + background-color: #E6E8E5; + border-bottom: 1px solid #d5d5d5; +}</programlisting> + Usage: Used to style the background color (and possibly + other attributes) for every other row within a table. + <programlisting>.portlet-table-selected { + color: #000; + font-size: 12px; + background-color: #CBD4E6; +}</programlisting> + Usage: Used to style text, color, etc. in a selected cell + range. + <programlisting>.portlet-table-subheader { + font-weight: bold; + color: #000; + font-size: 12px; +}</programlisting> + Usage: Used to style a subheading within a table that + gets rendered in a portlet. + <programlisting>.portlet-table-footer { + padding: 5px 5px 0 5px; + font-weight: bold; + color: #656565; + font-size: 12px; + border: none; + border-top: 1px solid #d5d5d5; +}</programlisting> + Usage: Similar to portlet-table-header and + portlet-table-body, this selector is used to style the table footer element + which is used to group the footer row in a table. + <programlisting>.portlet-table-text { + padding: 3px 5px; + border-bottom: 1px solid #d5d5d5; +}</programlisting> + Usage: Text that belongs to the table but does not fall in one of the other + categories (e.g. explanatory or help text that is associated with the table). + This selector can also be modified to provide styled text that can be used in + all tables that are rendered within a portlet. + </para> + </listitem> + <listitem> + <para>FONT Selectors + <programlisting>.portlet-font { + color: #000000; + font-family: Verdana, Arial, Helvetica, sans-serif; + font-size: 11px; +}</programlisting> + Usage: Used to style the font properties on text used in a portlet. Typically + this class is used for the display of non-accentuated information. + <programlisting>.portlet-font-dim { + color: #777777; + font-family: Verdana, Arial, Helvetica, sans-serif; + font-size: 11px; +}</programlisting> + Usage: A lighter version (color-wise) of the portlet-font selector. + </para> + </listitem> + <listitem> + <para>FORM Selectors + <programlisting>.portlet-form-label { + font-size: 10px; + color: #656565; +}</programlisting> + Usage: Text used for the descriptive label of an entire form (not the label for + each actual form field). + <programlisting>.portlet-form-button { + font-size: 10px; + font-weight: bold; + color: #FFFFFF; + background-color: #5078aa; + border-top: 1px solid #97B7C6; + border-left: 1px solid #97B7C6; + border-bottom: 1px solid #254869; + border-right: 1px solid #254869; +}</programlisting> + Usage: Used to style portlet form buttons (e.g. Submit). + <programlisting>.portlet-icon-label { + +}</programlisting> + Usage: Text that appears beside a context dependent + action icon. + <programlisting>.portlet-dlg-icon-label { + +}</programlisting> + Usage: Text that appears beside a "standard" icon (e.g + Ok, or Cancel). + <programlisting>.portlet-form-field-label { + font-family: Verdana, Arial, Helvetica, Sans-Serif, sans-serif; + font-size: 10px; + color: #000; + vertical-align: bottom; + white-space: nowrap +}</programlisting> + Usage: Selector used to style portlet form field labels. + <programlisting>.portlet-form-field { + font-family: Verdana, Arial, Helvetica, Sans-Serif, sans-serif; + font-size: 10px; + color: #000; /*margin-top: 10px;*/ +}</programlisting> + Usage: Selector used to style portlet form fields (i.e. INPUT controls, SELECT + elements, etc.). + </para> + </listitem> + <listitem> + <para>LINK Selectors + <programlisting>.portal-links:link { + font-family: Verdana, Arial, Helvetica, Sans-Serif, sans-serif; + font-size: 11px; + font-weight: bold; + color: #242424; + text-decoration: none; +} + +.portal-links:hover { + font-family: Verdana, Arial, Helvetica, Sans-Serif, sans-serif; + font-size: 11px; + font-weight: bold; + color: #5699B7; + text-decoration: none; +} + +.portal-links:active { + font-family: Verdana, Arial, Helvetica, Sans-Serif, sans-serif; + font-size: 11px; + font-weight: bold; + color: #242424; + text-decoration: none; +} + +.portal-links:visited { + font-family: Verdana, Arial, Helvetica, Sans-Serif, sans-serif; + font-size: 11px; + font-weight: bold; + color: #242424; + text-decoration: none; +}</programlisting> + Usage: The above four selectors are used to style links in the portal. Each + pseudo class (i.e. hover, active, etc.) provides a different link style. + </para> + </listitem> + <listitem> + <para>MESSAGE Selectors + <programlisting>.portlet-msg-status { + font-family: Verdana, Arial, Helvetica, Sans-Serif, sans-serif; + font-size: 12px; + font-style: normal; + color: #336699; +}</programlisting> + Usage: Selector used to signify the status of a current operation that takes + place in the portlet (e.g. "saving results", "step 1 of 4"). + <programlisting>.portlet-msg-info { + font-family: Verdana, Arial, Helvetica, Sans-Serif, sans-serif; + font-size: 12px; + font-style: italic; + color: #000; +}</programlisting> + Usage: Selector used to signify general information in a portlet (e.g. help + messages). + <programlisting>.portlet-msg-error { + color: red; + font-family: Verdana, Arial, Helvetica, Sans-Serif, sans-serif; + font-size: 12px; + font-weight: bold; +}</programlisting> + Usage: Selector used to signify an error message in the portlet (e.g. form + validation error). + <programlisting>.portlet-msg-alert { + font-family: Verdana, Arial, Helvetica, Sans-Serif, sans-serif; + font-size: 12px; + font-weight: bold; + color: #821717; +}</programlisting> + Usage: Selector used to style an alert that is displayed to the user. + <programlisting>.portlet-msg-success { + font-family: Verdana, Arial, Helvetica, Sans-Serif, sans-serif; + font-size: 12px; + font-weight: bold; + color: #359630; +}</programlisting> + Usage: Selector used to indicate successful completion of an action in a + portlet (e.g. "save successful"). + </para> + </listitem> + <listitem> + <para>SECTION Selectors + <programlisting>.portlet-section-header { + font-weight: bold; + color: #656565; + font-size: 12px; +} +</programlisting> + Usage: Table or section header. + <programlisting>.portlet-section-body { + color: #656565; +}</programlisting> + Usage: Normal text in a table cell. + <programlisting>.portlet-section-alternate { + background-color: #F2F2F2; +}</programlisting> + Usage: Used to style background color and text in every other table row. + <programlisting>.portlet-section-selected { + background-color: #CBD4E6; +}</programlisting> + Usage: Used to style background and font properties in a selected cell range. + <programlisting>.portlet-section-subheader { + font-weight: bold; + font-size: 10px; +}</programlisting> + Usage: Used to style a subheading within a table/section that gets rendered in + a portlet. + <programlisting>.portlet-section-footer { + font-size: 11px; +}</programlisting> + Usage: Used to style footer area of a section/table that gets rendered in a + portlet. + <programlisting>.portlet-section-text { + font-size: 12px; + font-style: italic; +}</programlisting> + Usage: Text that belongs to a section but does not fall in + one of the other categories. This selector can also be modified to provide + styled text that can be used in all sections that are rendered within a + portlet. + </para> + </listitem> + <listitem> + <para>MENU Selectors + <programlisting> +.portlet-menu {} + </programlisting> + Usage: General menu settings such as background color, + margins, etc. + <programlisting>.portlet-menu-item { + color: #242424; + text-decoration: none; + font-family: Verdana, Arial, Helvetica, sans-serif; + font-size: 12px; +}</programlisting> + Usage: Normal, unselected menu item. + <programlisting>.portlet-menu-item:hover { + color: #5699B7; + text-decoration: none; + font-family: Verdana, Arial, Helvetica, sans-serif; + font-size: 12px; +}</programlisting> + Usage: Used to style hover effect on a normal, unselected + menu item. + <programlisting> +.portlet-menu-item-selected {} + </programlisting> + Usage: Applies to selected menu items. + <programlisting> +.portlet-menu-item-selected:hover {} + </programlisting> + Usage: Selector styles the hover effect on a selected menu + item. + <programlisting> +.portlet-menu-cascade-item {} + </programlisting> + Usage: Normal, unselected menu item that has sub-menus. + <programlisting> +.portlet-menu-cascade-item-selected {} + </programlisting> + Usage: Selected sub-menu item. + <programlisting> +.portlet-menu-description {} + </programlisting> + Usage: Descriptive text for the menu (e.g. in a help + context below the menu). + <programlisting> +.portlet-menu-caption {} + </programlisting> + Usage: Selector used to style menu captions. + </para> + </listitem> + <listitem> + <para>WSRP Selectors + <programlisting> +.portlet-horizontal-separator {} + </programlisting> + Usage: A separator bar similar to a horizontal rule, but + with styling matching the page. + <programlisting> +.portlet-nestedTitle-bar {} + </programlisting> + Usage: Allows portlets to mimic the title bar when nesting + something. + <programlisting> +.portlet-nestedTitle {} + </programlisting> + Usage: Allows portlets to match the textual character of + the title on the title bar. + <programlisting> +.portlet-tab {} + </programlisting> + Usage: Support portlets having tabs in the same style as + the page or other portlets. + <programlisting> +.portlet-tab-active {} + </programlisting> + Usage: Highlight the tab currently being shown. + <programlisting> +.portlet-tab-selected {} + </programlisting> + Usage: Highlight the selected tab (not yet active). + <programlisting> +.portlet-tab-disabled {} + </programlisting> + Usage: A tab which can not be currently activated. + <programlisting> +.portlet-tab-area {} + </programlisting> + Usage: Top level style for the content of a tab. + </para> + </listitem> + </itemizedlist> + + </section> + </section> + <section> + <title>Additional Ajax selectors</title> + <para>Since 2.6 JBoss Portal has ajax features. Those features introduce a couple of + CSS selectors that enables further customization of the visual look and feel. Indeed by default + those CSS styles are provided by ajaxified layouts but it may not fit with some themes. It is possible + to redefine them in the stylesheet of the themes.</para> + <itemizedlist> + <listitem><para> + <programlisting> +.dyna-region {} + </programlisting> + + Usage: + Denotes a dynamic region which can be subject to ajax capabilities.</para> + </listitem> + <listitem><para> + <programlisting> +.dyna-window {} + </programlisting> + + Usage: + Denotes a dynamic window which can be subject to ajax capabilities.</para> + </listitem> + <listitem><para> + <programlisting> +.dyna-decoration {} + </programlisting> + + Usage: + Denotes a dynamic decorator which can be subject to ajax capabilities.</para> + </listitem> + <listitem><para> + <programlisting> +.dyna-portlet {} + </programlisting> + + Usage: + Denotes a dynamic content which can be subject to ajax capabilities.</para> + </listitem> + <listitem><para> + <programlisting> +.dnd-handle { + cursor: move; +} + </programlisting> + + Usage: + Denotes the handle offered by draggable windows. By default it changes the mouse shape to indicate + to the user that his mouse is hovering a draggable window.</para> + </listitem> + <listitem><para> + <programlisting> +.dnd-droppable { + border: red 1px dashed; + background-color: Transparent; +} + </programlisting> + + Usage: + Denotes a zone where a user can drop a window during drag and drop operations. This selector is added + and removed dynamically at runtime by the ajax framework and is not present in the generated markup.</para> + </listitem> + </itemizedlist> + </section> +</chapter> + <chapter id="ajax"> +<!-- <chapterinfo> + <author> + <firstname>Julien</firstname> + <surname>Viet</surname> + </author> + </chapterinfo>--> + <title>Ajax</title> + <para>This section covers the ajax features provided by the portal.</para> + <section> + <title>Introduction</title> + <para>Todo</para> + </section> + <section> + <title>Ajaxified markup</title> + <section> + <title>Ajaxified layouts</title> + <para>Part of the Ajax capabilities are implemented in the layout framework which provide the structure for + generating portal pages. The good news is that the existing layout only requires a few modifications in + order to be ajaxified.</para> + <para>We will use as example an simplified version of the layout JSP provided in JBoss Portal 2.6 and outline + what are the required changes that makes it an ajaxified layout: + <programlisting><![CDATA[ +<%@ taglib uri="/WEB-INF/theme/portal-layout.tld" prefix="p" %> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> + <meta http-equiv="Content-Type" content="text/html;"/> + <!-- inject the theme, default to the Renaissance theme if + nothing is selected for the portal or the page --> + <p:theme themeName="renaissance"/> + <!-- insert header content that was possibly set by portlets on the page --> + <p:headerContent/> +</head> + +<body id="body"> +<p:region regionName='AJAXScripts' regionID='AJAXScripts'/> +<div id="portal-container"> + <div id="sizer"> + <div id="expander"> + <div id="logoName"></div> + <table border="0" cellpadding="0" cellspacing="0" id="header-container"> + <tr> + <td align="center" valign="top" id="header"> + + <!-- Utility controls --> + <p:region regionName='dashboardnav' regionID='dashboardnav'/> + + <!-- navigation tabs and such --> + <p:region regionName='navigation' regionID='navigation'/> + <div id="spacer"></div> + </td> + </tr> + </table> + <div id="content-container"> + <!-- insert the content of the 'left' region of the page, + and assign the css selector id 'regionA' --> + <p:region regionName='left' regionID='regionA'/> + <!-- insert the content of the 'center' region of the page, + and assign the css selector id 'regionB' --> + <p:region regionName='center' regionID='regionB'/> + <hr class="cleaner"/> + </div> + </div> + </div> +</div> + +<p:region regionName='AJAXFooter' regionID='AJAXFooter'/> + +</body> +</html> +]]></programlisting> + <itemizedlist> + <listitem><para><![CDATA[<p:theme themeName="renaissance"/>]]> should be already present as it exists since 2.4 but is even more + necessary as it will inject in the page the reference to the ajax stylesheet.</para></listitem> + <listitem><para><![CDATA[<p:region regionName='AJAXScripts' regionID='AJAXScripts'/>]]> should be added before any other region + in the markup of the layout.</para></listitem> + <listitem><para><![CDATA[<p:region regionName='AJAXFooter' regionID='AJAXFooter'/>]]> should be added after any other region + in the markup of the layout.</para></listitem> + </itemizedlist> + </para> + </section> + <section> + <title>Ajaxified renderers</title> + <para>At runtime the portal combines the layout and the renderers in order create the markup returned to the + web browser. The most used render set is the divRenderer. Renderers only need a modification in the deployment + descriptor to indicate that they support ajax. Here is the declaration of the default divRenderer now in 2.6:</para> + <programlisting role="XML"><![CDATA[ +<renderSet name="divRenderer"> + <set content-type="text/html"> + <ajax-enabled>true</ajax-enabled> + <region-renderer>org.jboss.portal.theme.impl.render.div.DivRegionRenderer + </region-renderer> + <window-renderer>org.jboss.portal.theme.impl.render.div.DivWindowRenderer + </window-renderer> + <portlet-renderer>org.jboss.portal.theme.impl.render.div.DivPortletRenderer + </portlet-renderer> + <decoration-renderer>org.jboss.portal.theme.impl.render.div.DivDecorationRenderer + </decoration-renderer> + </set> +</renderSet> +]]></programlisting> + <para>You should notice the <![CDATA[<ajax-enabled>true</ajax-enabled>]]> which indicates that the render set + supports ajaxification.</para> + </section> + </section> + <section> + <title>Ajaxified pages</title> + <para>The ajaxification of the portal pages can be configured in a fine grained manner. Thanks to the portal + object properties it is possible to control which pages support ajax and which page do not support ajax. The + administrator must pay attention to the fact that property values are inherited in the object hierarchy.</para> + <section> + <title>Drag and Drop</title> + <para>That feature is only effective in dashboards as it requires the offer personalization of the page + layout per user. By default the feature is enabled thanks to a property set on the dashboard object. + It is possible to turn off that property if the administrator does not want to expose that feature + to its user.</para> + <para>In the file <emphasis>jboss-portal.sar/conf/data/default-object.xml</emphasis> is declared and configured the + creation of the dashboard portal:</para> + <programlisting role="XML"><![CDATA[ +<deployment> + <parent-ref/> + <if-exists>keep</if-exists> + <context> + <context-name>dashboard</context-name> + <properties> + ... + <property> + <name>theme.dyna.dnd_enabled</name> + <value>true</value> + </property> + ... + </properties> + ... + </context> +</deployment> +]]></programlisting> + <para>The property <emphasis>theme.dyna.dnd_enabled</emphasis> is set to the value <emphasis>true</emphasis> + which means that the dashboard object will provide the drag and drop feature. + </para> + </section> + <section> + <title>Partial refresh</title> + <para>Partial refresh is a very powerful feature which allows the portal to optimize the refreshing + of portlets on a page. When one portlet is invoked, instead of redrawing the full page, the portal is able + to detect which portlets needs to be refreshed and will update only these portlets.</para> + <mediaobject> + <imageobject> + <imagedata fileref="images/ajax/partial-refresh.png" format="PNG" scalefit="1"/> + </imageobject> + </mediaobject> + <para>The portal providing partial refresh.</para> + + <section> + <title>Portal objects configuration</title> + <para>Like with the drag and drop feature, partial page refresh is controlled via properties on portal objects. + The name of the property is <emphasis>theme.dyna.partial_refresh_enabled</emphasis> and its values can + be <emphasis>true</emphasis> or <emphasis>false</emphasis>. When this property is set on an object + it is automatically inherited by the sub hierarchy located under that object. By default the drag + and drop feature is positioned on the dashboard object and not on the rest of the portal objects. + </para> + <programlisting role="XML"><![CDATA[ +<deployment> + <parent-ref/> + <if-exists>keep</if-exists> + <context> + <context-name>dashboard</context-name> + <properties> + ... + <property> + <name>theme.dyna.partial_refresh_enabled</name> + <value>true</value> + </property> + ... + </properties> + ... + </context> +</deployment> +]]></programlisting> + <note> + <para>The partial page refresh feature is compatible with the Portal API. The Portal API allows programmatic + update of the state of portlets at runtime. For instance it is possible to modify the window state or + the mode of several portlets on a given page. When such event occurs, the portal detects the changes + which occurred and will update the portlet fragments in the page.</para> + </note> + <para>It is possible to change that behavior at runtime using the property editor of the management portlet. + If you want to enable partial refreshing on the default portal you should set the property to true + directly on the portal and all the pages in that portal will automatically inherit those properties.</para> + <mediaobject> + <imageobject> + <imagedata fileref="images/ajax/partial-refresh-admin.png" format="PNG" scalefit="1"/> + </imageobject> + </mediaobject> + <para>The default portal configured for partial page refresh</para> + + </section> + <section> + <title>Portlet configuration</title> + <para> + By default any portlet will support partial refreshing. When does the portal performs partial page + refreshing ? By default it is enabled for action and render links with the following exceptions. In those + situations, the portal will prefer to perform a full page refresh: + <itemizedlist> + <listitem> + <para>Form GET are not handled, however it should not be an issue as this situation is discouraged + by the Portlet specification. It however taken in account, just in case of. Here is an example + of a JavaServer Page that would do one:</para> + <programlisting><![CDATA[ +<form action="<%= renderResponse.createActionURL() %>" method="get"> + ... +</form> +]]></programlisting> + </listitem> + <listitem> + <para>Form uploads are not handled.</para> + </listitem> + <listitem><para>Having an interaction that deals with the <emphasis>MAXIMIZED</emphasis> window state. + When a window is entering a maximized state or leaving a maximized window state, the portal will + perform a full page refresh.</para></listitem> + </itemizedlist> + </para> + <para>It can happen that a portlet does not want to support partial refreshing, in those situations + the <emphasis>jboss-portlet.xml</emphasis> can be used to control that behavior. Since 2.6 an ajax + section has been added in order to configure ajax features related to the portlet.</para> + <programlisting role="XML"><![CDATA[ +<portlet> + <portlet-name>MyPortletNoAjax</portlet-name> + <ajax> + <partial-refresh>false</partial-refresh> + </ajax> +</portlet> +]]></programlisting> + <para>The usage of the <emphasis>partial-refresh</emphasis> set to the value false means that + the portlet will not be subject of a partial page refresh when it is invoked. However the portlet + markup can still be subject to a partial rendering.</para> + </section> + <section> + <title>Limitations</title> + <para>Partial refreshing of portlets has limitations both on the server side (portal) and on the client side (browser).</para> + <section> + <title>Application scoped session attributes</title> + <para>When partial refresh is activated, the state of a page can potentially become inconsistent. for + example, if some objects are shared in the application scope of the session between portlets. When one + portlet update a session object, the other portlet won't be refreshed and will still display content based + on the previous value of the object in the session. To avoid that, partial refresh can be deactivated + for certain portlets by adding &lt;portlet-refresh&gt;false&lt;portlet-refresh&gt; in the jboss-portlet.xml file.</para> + </section> + <section> + <title>Non ajax interactions</title> + <para>The solution developed by JBoss Portal on the client side is built on top of DOM events emitted + by the web browser when the user interacts with the page. If an interaction is done without an + emission of an event then JBoss Portal will not be able to transform it into a partial refresh and + it will result instead of a full refresh. This can happen with programmatic submission of forms. + </para> + <programlisting role="XHTML"><![CDATA[ +<form id="<%= formId %>" action="<%= renderResponse.createActionURL() %>" method="post"> + ... + <select onclick="document.getElementById('<%= formId %>').submit()"> + ... + </select> + ... +</form> +]]></programlisting> + </section> + </section> + </section> + </section> +</chapter> + <chapter id="troubleshooting"> + <!-- <chapterinfo> + <author> + <firstname>Roy</firstname> + <surname>Russo</surname> + </author> + </chapterinfo>--> + <title>Troubleshooting and FAQ</title> + <section id="troubleshooting-faq"> + <title>Troubleshooting and FAQ</title> + <para> + <emphasis role="bold">Installation / Configuration</emphasis> + <itemizedlist> + <listitem><para> + <xref linkend="conf1"/> I am seeing "ERROR [JDBCExceptionReporter] Table not found in statement" in the + logfile + on first boot. What is this?</para> + </listitem> + <listitem><para> + <xref linkend="conf2"/> I want to do a clean install/upgrade over my existing one. What are the + steps?</para> + </listitem> + <listitem><para> + <xref linkend="conf3"/> Is my database vendor/version combination supported?</para> + </listitem> + <listitem> + <para><xref linkend="conf4"/> How do I force the Hibernate Dialect used for my database?</para> + </listitem> + <listitem> + <para> <xref linkend="conf5"/> How do I change the context-root of the portal to http://localhost:8080/?</para> + </listitem> + </itemizedlist> + </para> + <para> + <emphasis role="bold">CMS</emphasis> + <itemizedlist> + <listitem> + <para> <xref linkend="cms1"/>. How do I change the CMS repository configuration?</para> + </listitem> + <listitem> + <para> <xref linkend="cms2"/>.On reboot, the CMS is complaining about a locked repository.</para> + </listitem> + <listitem> + <para> <xref linkend="cms3"/>. I created a file in the CMSAdmin. How do I view it?</para> + </listitem> + </itemizedlist> + </para> + <para> + <emphasis role="bold">Errors</emphasis> + <itemizedlist> + <listitem> + <para> <xref linkend="error1"/>. When I access a specific portal-instance or page, I keep seeing "401 - not + authorized" error in my browser.</para> + </listitem> + <listitem> + <para> <xref linkend="error2"/>. How do I disable development-mode errors on the presentation layer?</para> + </listitem> + </itemizedlist> + </para> + <para> + <emphasis role="bold">Miscellaneous</emphasis> + <itemizedlist> + <listitem> + <para> <xref linkend="misc1"/>Is there a sample portlet I can look at to learn about portlet development and + JBoss + Portal deployments?</para> + </listitem> + </itemizedlist> + </para> + + + <section id="conf1"><title>"Error [JDBCExceptionReporter] Table not found in statement"</title> + <para> + <emphasis role="bold">I am seeing "ERROR [JDBCExceptionReporter] Table not found in statement" in the logfile + on first + boot. What is + this?</emphasis> + Ignore this error. It is used by the portal to create the initial database tables. On second boot, you should + not see them at all. + </para> +</section> + + <section id="conf2"><title>install/upgrade</title> + <para> + <emphasis role="bold">I want to do a clean install/upgrade over my existing one. What are the steps?</emphasis> + <itemizedlist> + <listitem><para>Shut down JBoss AS</para></listitem> + <listitem><para>Delete JBOSS_HOME/server/default/data/portal</para></listitem> + <listitem><para>Delete all JBoss Portal tables from your database</para></listitem> + <listitem><para>Start JBoss AS.</para></listitem> + </itemizedlist> + </para> +</section> + + <section id="conf3"><title>database support</title> + <para> + <emphasis role="bold">Is my database vendor/version combination supported?</emphasis> + See + <xref linkend="supportedversions-db"/> + </para> +</section> + + <section id="conf4"><title>Hibernate Dialect</title> + <para> + <emphasis role="bold">How do I force the Hibernate Dialect used for my database?</emphasis> + See + <xref linkend="configuration-hibdialect"/> + </para> +</section> + + <section id="conf5"><title>context-root</title> + <para> + <emphasis role="bold">How do I change the context-root of the portal to http://localhost:8080/?</emphasis> + See + <xref linkend="configuration-contextroot"/> + </para> +</section> + + <section id="cms1"><title>CMS repository configuration</title> + <para> + <emphasis role="bold">How do I change the CMS repository configuration?</emphasis> + + There are 3 supported modes: 100% DB (default), 100% Filsystem, and Mixed (Blobs on the Filesystem and metadata + in the DB). You can see configuration options here: + <xref linkend="configuration-cms"/> + </para> +</section> + <section id="cms2"><title>Locked repository</title> + <para> + <emphasis role="bold">On reboot, the CMS is complaining about a locked repository.</emphasis> + + This occurs when JBoss AS is improperly shutdown or the CMS Service errors on startup. To remove the lock, + shutdown JBoss, and then remove the file under JBOSS_HOME/server/default/data/portal/cms/conf/.lock. + </para> +</section> + + <section id="cms3"><title>CMSAdmin</title> + <para> + <emphasis role="bold">I created a file in the CMSAdmin. How do I view it?</emphasis> + + Using the default configuration, the path to the file in the browser would be: + http://localhost:8080/portal/content/path/to/file.ext. + Note that all requests for cms content must be prepended with /content and then followed by the + path/to/the/file.gif as it is in your directory structure. + </para> +</section> + + <section id="error1"><title>"401 - not authorised"</title> + <para> + <emphasis role="bold">When I access a specific portal-instance or page, I keep seeing "401 - not + authorized" error in my browser.</emphasis> + You are likely not authorized to view the page or portal instance. You can either modify the security using the + Management Portlet under the Admin Tab, or secure your portlets via the object descriptor, + <xref linkend="securing_objects"/> + </para> +</section> + + <section id="error2"><title>Development errors</title> + <para> + <emphasis role="bold">How do I disable development-mode errors on the presentation layer?</emphasis> + See: + <xref linkend="descriptor_debug"/> + </para> +</section> + <section id="misc1"><title>Portlet Deployment</title> + <para> + <emphasis role="bold">Is there a sample portlet I can look at to learn about portlet development and JBoss + Portal deployments?</emphasis> +</para> + + <itemizedlist> + <listitem><para>Sample portlets with tutorials can be found here, + <xref linkend="tutorials_tutorials"/></para> + </listitem> + <listitem><para>Additional Portlets can be found at + <ulink url="http://www.portletswap.com">PortletSwap.com</ulink> + .</para> + </listitem> + </itemizedlist> + </section> + + </section> +</chapter> + <!-- DO NOT EDIT ME DIRECTLY, I AM GENERATED FROM THE DTD USING THE dtd2docbook ANT TASK --><appendix id="portalObjectsDTD"> + <title>*-object.xml DTD</title> + <para> +<programlisting><![CDATA[ + + <?xml version="1.0" encoding="UTF-8" ?> + +<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~ JBoss, a division of Red Hat ~ + ~ Copyright 2006, Red Hat Middleware, LLC, and individual ~ + ~ contributors as indicated by the @authors tag. See the ~ + ~ copyright.txt in the distribution for a full listing of ~ + ~ individual contributors. ~ + ~ ~ + ~ This is free software; you can redistribute it and/or modify it ~ + ~ under the terms of the GNU Lesser General Public License as ~ + ~ published by the Free Software Foundation; either version 2.1 of ~ + ~ the License, or (at your option) any later version. ~ + ~ ~ + ~ This software is distributed in the hope that it will be useful, ~ + ~ but WITHOUT ANY WARRANTY; without even the implied warranty of ~ + ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU ~ + ~ Lesser General Public License for more details. ~ + ~ ~ + ~ You should have received a copy of the GNU Lesser General Public ~ + ~ License along with this software; if not, write to the Free ~ + ~ Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA ~ + ~ 02110-1301 USA, or see the FSF site: http://www.fsf.org. ~ + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--> + +<!-- +<!DOCTYPE deployments PUBLIC + "-//JBoss Portal//DTD Portal Object 2.6//EN" + "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd"> +--> + +<!-- +The deployements element is a generic container for deployment elements. +--> +<!ELEMENT deployments (deployment*)> + +<!-- +The deployment is a generic container for portal object elements. The parent-ref +child gives the name of the parent object that the current object will use as parent. +The optional if-exists element define the behavior when a portal object which +an identical name is already child of the parent element. The default behavior of +the if-exist tag is to keep the existing object and not create a new object. The +last element is the portal object itself. + +Example: + +<deployment> + <parent-ref>default</parent-ref> + <page> + ... + </page> +</deployment> + +All portal objects have a common configuration which can be : + +1/ a listener : specifies the id of a listener is the listener registry. A listener +object is able to listen portal events which apply to the portal node hierarchy. + +2/ properties : a set of generic properties owned by the portal object. Some +properties can drive the behavior of the object. + +3/ security-constraint : defines security configuration of the portal object. + +--> +<!ELEMENT deployment (parent-ref?,if-exists?,(context|portal|page|window))> + +<!-- +Contains a reference to the parent object. The naming convention for naming object +is to concatenate the names of the path to the object and separate the names by a dot. +If the path is empty then the empty string must be used. + +Example: + +<parent-ref/> the root having an empty path + +<parent-ref>default</parent-ref> the object with the name default under the root +having the path (default) + +<parent-ref>default.default</parent-ref> the object with the path (default,default) + +--> +<!ELEMENT parent-ref (#PCDATA)> + +<!-- +The authorized values are overwrite and keep. Overwrite means that the existing +object will be destroyed and the current declaration will be used. Keep means that +the existing object will not be destroyed and no creation hence will be done. +--> +<!ELEMENT if-exists (#PCDATA)> + +<!-- +A portal object of type context. A context type represent a node in the tree which +does not have a visual representation. It can exist only under the root. A context can +only have children with the portal type. +--> +<!ELEMENT context (context-name,properties?,listener?,security-constraint?,portal*, + (display-name* | (resource-bundle, supported-locale+)))> + +<!-- +The context name value. +--> +<!ELEMENT context-name (#PCDATA)> + +<!-- +A portal object of type portal. A portal type represents a virtual portal and can +have children of type page. In addition of the common portal object elements it support +also the declaration of the modes and the window states it supports. If no declaration +of modes or window states is done then the default value will be respectively +(view,edit,help) and (normal,minimized,maximized). +--> +<!ELEMENT portal (portal-name,supported-modes,supported-window-states?,properties?, + listener?,security-constraint?,page*, + (display-name* | (resource-bundle, supported-locale+)))> + +<!-- +The portal name value. +--> +<!ELEMENT portal-name (#PCDATA)> + + +<!-- +The supported modes of a portal. + +Example: + +<supported-mode> + <mode>view</mode> + <mode>edit</mode> + <mode>help</mode> +</supported-mode> +--> +<!ELEMENT supported-modes (mode*)> + +<!-- +A portlet mode value. +--> +<!ELEMENT mode (#PCDATA)> + +<!-- +The supported window states of a portal. + +Example: + +<supported-window-states> + <window-state>normal</window-state> + <window-state>minimized</window-state> + <window-state>maximized</window-state> +</supported-window-states> + +--> +<!ELEMENT supported-window-states (window-state*)> + +<!-- +A window state value. +--> +<!ELEMENT window-state (#PCDATA)> + +<!-- +A portal object of type page. A page type represents a page which can have children of +type page and window. The children windows are the windows of the page and the children +pages are the subpages of this page. +--> +<!ELEMENT page (page-name,properties?,listener?,security-constraint?,(page|window)*, + (display-name* | (resource-bundle, supported-locale+)))> + +<!ELEMENT display-name (#PCDATA)> +<!ATTLIST display-name + xml:lang NMTOKEN #IMPLIED +> + +<!ELEMENT resource-bundle (#PCDATA)> + +<!ELEMENT supported-locale (#PCDATA)> + +<!-- +The page name value. +--> +<!ELEMENT page-name (#PCDATA)> + +<!-- +A portal object of type window. A window type represents a window. Beside the common +properties a window has a content and belong to a region on the page. + +The instance-ref or content tags are used to define the content of the window. The +usage of the content tag is generic and can be used to describe any kind of content. +The instance-ref is a shortcut to define a content type of portlet which points to a +portlet instance. + +The region and height defines how the window is placed in the page. +--> +<!ELEMENT window (window-name,(instance-ref|content),region,height, + initial-window-state?,initial-mode?,properties?,listener?, + (display-name* | (resource-bundle, supported-locale+)))> + +<!-- +The window name value. +--> +<!ELEMENT window-name (#PCDATA)> + +<!-- +Define the content of the window as a reference to a portlet instance. The value +is the id of the instance. + +Example: + +<instance-ref>MyPortletInstance</instance-ref> + +--> +<!ELEMENT instance-ref (#PCDATA)> + +<!-- +Define the content of the window in a generic manner. The content is define by +the type of the content and an URI which acts as an identificator for the content. + +Example: + +<content> + <content-type>portlet</content-type> + <content-uri>MyPortletInstance</content-uri> +</content> + +<content> + <content-type>cms</content-type> + <content-uri>/default/index.html</content-uri> +</content> + +--> +<!ELEMENT content (content-type,content-uri)> + +<!-- +The content type of the window. +--> +<!ELEMENT content-type (#PCDATA)> + +<!-- +The content URI of the window. +--> +<!ELEMENT content-uri (#PCDATA)> + +<!-- +The region the window belongs to. +--> +<!ELEMENT region (#PCDATA)> + +<!-- +The window state to use when the window is first accessed +--> +<!ELEMENT initial-window-state (#PCDATA)> + +<!-- +The mode to use when the window is first accessed +--> +<!ELEMENT initial-mode (#PCDATA)> + +<!-- +The height of the window in the particular region. +--> +<!ELEMENT height (#PCDATA)> + +<!-- +Define a listener for a portal object. The value is the id of the listener. +--> +<!ELEMENT listener (#PCDATA)> + +<!-- +A set of generic properties for the portal object. +--> +<!ELEMENT properties (property*)> + +<!-- +A generic string property. +--> +<!ELEMENT property (name,value)> + +<!-- +A name value. +--> +<!ELEMENT name (#PCDATA)> + +<!-- +A value. +--> +<!ELEMENT value (#PCDATA)> + +<!-- +The security-constraint element is a container for policy-permission elements + +Examples: + +<security-constraint> + <policy-permission> + <role-name>User</role-name> + <action-name>view</action-name> + </policy-permission> +</security-constraint> + +<security-constraint> + <policy-permission> + <unchecked/> + <action-name>view</action-name> + </policy-permission> +</security-constraint> +--> +<!ELEMENT security-constraint (policy-permission*)> + +<!-- +The policy-permission element is used to secure a specific portal page based on a +user's role. +--> +<!ELEMENT policy-permission (action-name*,unchecked?,role-name*)> + +<!-- +The role-name element is used to define a role that this security constraint will apply to + + * <role-name>SOMEROLE</role-name> Access to this portal page is limited to the defined role. +--> +<!ELEMENT action-name (#PCDATA)> + +<!-- +The unchecked element is used to define (if present) that anyone can view this portal page +--> +<!ELEMENT unchecked EMPTY> + +<!-- +The action-name element is used to define the access rights given to the role defined. +Possible values are: + + * view - Users can view the page. +--> +<!ELEMENT role-name (#PCDATA)> + + +]]></programlisting> + </para> +</appendix> + <!-- DO NOT EDIT ME DIRECTLY, I AM GENERATED FROM THE DTD USING THE dtd2docbook ANT TASK --><appendix id="portletInstancesDTD"> + <title>portlet-instances.xml DTD</title> + <para> +<programlisting><![CDATA[ + + <?xml version="1.0" encoding="UTF-8" ?> + +<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~ JBoss, a division of Red Hat ~ + ~ Copyright 2006, Red Hat Middleware, LLC, and individual ~ + ~ contributors as indicated by the @authors tag. See the ~ + ~ copyright.txt in the distribution for a full listing of ~ + ~ individual contributors. ~ + ~ ~ + ~ This is free software; you can redistribute it and/or modify it ~ + ~ under the terms of the GNU Lesser General Public License as ~ + ~ published by the Free Software Foundation; either version 2.1 of ~ + ~ the License, or (at your option) any later version. ~ + ~ ~ + ~ This software is distributed in the hope that it will be useful, ~ + ~ but WITHOUT ANY WARRANTY; without even the implied warranty of ~ + ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU ~ + ~ Lesser General Public License for more details. ~ + ~ ~ + ~ You should have received a copy of the GNU Lesser General Public ~ + ~ License along with this software; if not, write to the Free ~ + ~ Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA ~ + ~ 02110-1301 USA, or see the FSF site: http://www.fsf.org. ~ + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--> + +<!-- +<!DOCTYPE deployments PUBLIC + "-//JBoss Portal//DTD Portlet Instances 2.6//EN" + "http://www.jboss.org/portal/dtd/portlet-instances_2_6.dtd"> +--> + +<!-- +The deployements element is a container for deployment elements. +--> +<!ELEMENT deployments (deployment*)> + +<!-- +The deployment is a container for an instance element. +--> +<!ELEMENT deployment (if-exists?,instance)> + +<!-- +The if-exists element is used to define action to take if instance with such name is +already present. Possible values are overwrite or keep . Overwrite will destroy the +existing object in the database and create a new one, based on the content of the +deployment. Keep will maintain the existing object deployment or create a new one if +it does not yet exist. +--> +<!ELEMENT if-exists (#PCDATA)> + +<!-- +The instance element is used to create an instance of a portlet from the portlet +application of the same war file containing the portlet-instances.xml file. The portlet +will be created and configured only if the portlet is present and an instance with +such a name does not already exist. + +Example : + +<instance> + <instance-id>MyPortletInstance</instance-id> + <portlet-ref>MyPortlet</portlet-ref> + <preferences> + <preference> + <name>abc</name> + <value>def</value> + </preference> + </preferences> + <security-constraint> + <policy-permission> + <role-name>User</role-name> + <action-name>view</action-name> + </policy-permission> + </security-constraint> +</instance> + +--> +<!ELEMENT instance (instance-id,portlet-ref,display-name*,preferences?, + security-constraint?, (display-name* | (resource-bundle, supported-locale+)))> + +<!ELEMENT display-name (#PCDATA)> +<!ATTLIST display-name + xml:lang NMTOKEN #IMPLIED +> + +<!ELEMENT resource-bundle (#PCDATA)> + +<!ELEMENT supported-locale (#PCDATA)> + + +<!-- +The identifier of the instance. +--> +<!ELEMENT instance-id (#PCDATA)> + +<!-- +The reference to the portlet which is its portlet name. +--> +<!ELEMENT portlet-ref (#PCDATA)> + +<!-- +Display name is the string used to represent this instance +--> +<!ELEMENT display-name (#PCDATA)> +<!ATTLIST display-name + xml:lang NMTOKEN #IMPLIED +> + +<!-- +The preferences element configures the instance with a specific set of preferences. +--> +<!ELEMENT preferences (preference+)> + +<!-- +The preference configure one preference of a set of preferences. +--> +<!ELEMENT preference (name,value)> + +<!-- +A name. +--> +<!ELEMENT name (#PCDATA)> + +<!-- +A string value. +--> +<!ELEMENT value (#PCDATA)> + +<!-- +The security-constraint element is a container for policy-permission elements + +Examples: + +<security-constraint> + <policy-permission> + <role-name>User</role-name> + <action-name>view</action-name> + </policy-permission> +</security-constraint> + +<security-constraint> + <policy-permission> + <unchecked/> + <action-name>view</action-name> + </policy-permission> +</security-constraint> +--> +<!ELEMENT security-constraint (policy-permission*)> + +<!-- +The policy-permission element is used to secure a specific portlet instance based on a +user's role. +--> +<!ELEMENT policy-permission (action-name*,unchecked?,role-name*)> + +<!-- +The action-name element is used to define the access rights given to the role defined. +Possible values are: + + * view - Users can view the page. + * viewrecursive - Users can view the page and child pages. + * personalize - Users are able to view AND personalize the page. + * personalizerecursive - Users are able to view AND personalize the page AND its child + pages. +--> +<!ELEMENT action-name (#PCDATA)> + +<!-- +The unchecked element is used to define (if present) that anyone can view this instance +--> +<!ELEMENT unchecked EMPTY> + +<!-- +The role-name element is used to define a role that this security constraint will apply to + + * <role-name>SOMEROLE</role-name> Access to this instance is limited to the defined role. +--> +<!ELEMENT role-name (#PCDATA)> + + +]]></programlisting> + </para> +</appendix> + <!-- DO NOT EDIT ME DIRECTLY, I AM GENERATED FROM THE DTD USING THE dtd2docbook ANT TASK --><appendix id="jbossPortletDTD"> + <title>jboss-portlet.xml DTD</title> + <para> +<programlisting><![CDATA[ + + <?xml version="1.0" encoding="UTF-8" ?> + +<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~ JBoss, a division of Red Hat ~ + ~ Copyright 2006, Red Hat Middleware, LLC, and individual ~ + ~ contributors as indicated by the @authors tag. See the ~ + ~ copyright.txt in the distribution for a full listing of ~ + ~ individual contributors. ~ + ~ ~ + ~ This is free software; you can redistribute it and/or modify it ~ + ~ under the terms of the GNU Lesser General Public License as ~ + ~ published by the Free Software Foundation; either version 2.1 of ~ + ~ the License, or (at your option) any later version. ~ + ~ ~ + ~ This software is distributed in the hope that it will be useful, ~ + ~ but WITHOUT ANY WARRANTY; without even the implied warranty of ~ + ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU ~ + ~ Lesser General Public License for more details. ~ + ~ ~ + ~ You should have received a copy of the GNU Lesser General Public ~ + ~ License along with this software; if not, write to the Free ~ + ~ Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA ~ + ~ 02110-1301 USA, or see the FSF site: http://www.fsf.org. ~ + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--> + +<!-- The additional configuration elements of the JBoss portlet container. + +<!DOCTYPE portlet-app PUBLIC + "-//JBoss Portal//DTD JBoss Portlet 2.6//EN" + "http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd"> +--> + +<!-- +The remotable element is used to configure the default behavior of the portlets with +respect to WSRP exposure. + +For each portlet defined in portlet.xml, it is possible to configure specific +settings of the portlet container. + +It is also possible to inject services in the portlet context of the application +using the service elements. +--> +<!ELEMENT portlet-app (remotable?,portlet*,service*)> + +<!-- +Additional configuration for a portlet. + +The portlet-name defines the name of the portlet. It must match a portlet defined already +in portlet.xml of the same web application. + +The remotable element configures the portlet exposure to WSRP. If no value is present +then the value considered is either the value defined globally at the portlet +application level or false. + +The trans-attribute value specifies the behavior of the portlet when it is invoked at +runtime with respect to the transactionnal context. According to how the portlet is +invoked a transaction may exist or not before the portlet is invoked. Usually in the +local context the portal transaction could be present. By default the value considered is + NotSupported which means that the portal transaction will be suspended for the duration + of the portlet invocation. + +Example: + +<portlet> + <portlet-name>MyPortlet</portlet-name> + <remotable>true</remotable> + <trans-attribute>Required</trans-attribute> +</portlet> + +--> +<!ELEMENT portlet (portlet-name,remotable?,ajax?,session-config?,transaction?, + header-content?,portlet-info?)> + +<!-- +The portlet name. +--> +<!ELEMENT portlet-name (#PCDATA)> + +<!-- +The remotable value is used for WSRP exposure. The accepted values are the +litterals true of false. +--> +<!ELEMENT remotable (#PCDATA)> + +<!-- +The ajax tag allows to configure the ajax capabilities of the portlet. If +the portlet is tagged as partial-refresh then the portal may use partial page +refreshing and render only that portlet. If the portlet partial-refresh value +is false, then the portal will perform a full page refresh when the portlet is refreshed. +--> +<!ELEMENT ajax (partial-refresh)> + +<!-- +The authorized values for the partial-refresh element are true or false. +--> +<!ELEMENT partial-refresh (#PCDATA)> + +<!-- +Additional portlet information +--> +<!ELEMENT portlet-info (icon?)> + +<!-- +Defines icons for the portlet, they can be used by the administration portlet +to represent a particular portlet. +--> +<!ELEMENT icon (small-icon?, large-icon?)> + +<!-- +A small icon image, usually 16x16, gif, jpg and png are usually supported. +An absolute URL or a URL starting with a '/' in the context of the webapp are accepted: +eg. http://www.example.com/images/smallIcon.png +eg. /images/smallIcon.png +--> +<!ELEMENT small-icon (#PCDATA)> + +<!-- +A large icon image, usually 32x32, gif, jpg and png are usually supported. +An absolute URL or a URL starting with a '/' in the context of the webapp are accepted: +eg. http://www.example.com/images/smallIcon.png +eg. /images/smallIcon.png +--> +<!ELEMENT large-icon (#PCDATA)> + +<!-- +This element configure the portlet session of the portlet. + +The distributed element instructs the container to distribute the session attributes +using the portal session replication. It applies only to local portlets are not to +remote portlets. The default value is false. + +Example: + +<session-config> + <distributed>true</distributed> +</session-config> + +--> +<!ELEMENT session-config (distributed)> + +<!-- +The authorized values for the distributed element are true or false. +--> +<!ELEMENT distributed (#PCDATA)> + +<!-- +Defines how the portlet behaves with the transactionnal context. The default value +is Never. + +Example: + +<transaction> + <trans-attribute>Required</transaction> +<transaction> +--> +<!ELEMENT transaction (trans-attribute)> + +<!-- +The trans-attribute value defines the transactionnal behavior. The accepted values +are Required, Mandatory, Never, Supports, NotSupported and RequiresNew. +--> +<!ELEMENT trans-attribute (#PCDATA)> + +<!-- +Specify content which should be included in the portal aggregated page when the portlet +is present on that page. This setting only applies when the portlet is used in the local mode. +--> +<!ELEMENT header-content (link|script|meta)*> + +<!-- +Creates a header markup element for linked resources, +see http://www.w3.org/TR/html401/struct/links.html#h-12.3 + +At runtime the href attribute value will be prefixed with the context path +of the web application. + +Example: + +<link rel="stylesheet" type="text/css" href="/style.css" media="screen"/> + +will produce at runtime the following markup + +<link rel="stylesheet" type="text/css" href="/my-web-application/style.css" media="screen"/> +--> +<!ATTLIST link + href CDATA #IMPLIED + rel CDATA #IMPLIED + type CDATA #IMPLIED + media CDATA #IMPLIED + title CDATA #IMPLIED> + +<!-- +No content is allowed inside an link element. +--> +<!ELEMENT link EMPTY> + +<!-- +Creates a header markup for scripting, +see http://www.w3.org/TR/html401/interact/scripts.html + +At runtime the src attribute value will be prefixed with the context path +of the web application. + +Example 1: + +<script type="text/javascript" src="/myscript.js"></script> + +will produce at runtime the following markup + +<script type="text/javascript" src="/my-web-application/myscript.js"></script> + +Example 2: + +<script type="text/javascript"> + function hello() { + alert('Hello'); + } +</script> +--> +<!ATTLIST script + src CDATA #IMPLIED + type CDATA #IMPLIED + language CDATA #IMPLIED> + +<!-- +The script header element can contain inline script definitions. +--> +<!ELEMENT script (#PCDATA)> + +<!-- +Creates a header markup for adding meta data to a page, +see http://www.w3.org/TR/html401/struct/global.html#h-7.4.4 + +Example: + +<meta name="keywords" content="jboss, portal, redhat"/> +--> +<!ATTLIST meta + name CDATA #REQUIRED + content CDATA #REQUIRED> + +<!-- +No content is allowed for meta element. +--> +<!ELEMENT meta EMPTY> + +<!-- +Declare a service that will be injected by the portlet container as an +attribute of the portlet context. + +Example: + +<service> + <service-name>UserModule</service-name> + <service-class>org.jboss.portal.identity.UserModule</service-class> + <service-ref>:service=Module,type=User</service-ref> +</service> + +In the portlet it is then possible to use it by doing a lookup on the service +name, for example in the init() lifecycle method : + +public void init() +{ + UserModule userModule = (UserModule)getPortletContext().getAttribute("UserModule"); +} + +--> +<!ELEMENT service (service-name,service-class,service-ref)> + +<!-- +The service name that will be used to bind the service as a portlet context attribute. +--> +<!ELEMENT service-name (#PCDATA)> + +<!-- +The full qualified name of the interface that the service implements. +--> +<!ELEMENT service-class (#PCDATA)> + +<!-- +The reference to the service. In the JMX Microkernel environment it consist of the JMX +name of the service MBean. For an MBean reference if the domain is left out, then the +current domain of the portal will be used. +--> +<!ELEMENT service-ref (#PCDATA)> + + +]]></programlisting> + </para> +</appendix> +</book> Modified: docs/enterprise/trunk/Reference_Guide/pom.xml =================================================================== --- docs/enterprise/trunk/Reference_Guide/pom.xml 2008-11-12 22:44:10 UTC (rev 12288) +++ docs/enterprise/trunk/Reference_Guide/pom.xml 2008-11-12 23:51:15 UTC (rev 12289) @@ -33,7 +33,8 @@ <configuration> <!--minmemory>1024m</minmemory> <maxmemory>1024m</maxmemory --> - <sourceDocumentName>resolved.xml</sourceDocumentName> + <!--sourceDocumentName>resolved.xml</sourceDocumentName--> + <sourceDocumentName>JBoss_Portal_Reference_Guide.xml</sourceDocumentName> <sourceDirectory>en-US</sourceDirectory> <imageResource> <directory>en-US</directory> Modified: docs/enterprise/trunk/Reference_Guide/tmp/en-US/xml/Book_Info.xml =================================================================== --- docs/enterprise/trunk/Reference_Guide/tmp/en-US/xml/Book_Info.xml 2008-11-12 22:44:10 UTC (rev 12288) +++ docs/enterprise/trunk/Reference_Guide/tmp/en-US/xml/Book_Info.xml 2008-11-12 23:51:15 UTC (rev 12289) @@ -11,6 +11,7 @@ <productnumber>2.7</productnumber> <pubdate>Oct, 2007</pubdate> <isbn>N/A</isbn> + <issuenum>1</issuenum> <abstract> <para>This book is a JBoss Portal 2.7 Reference Guide.</para></abstract> <corpauthor> Modified: docs/enterprise/trunk/Reference_Guide/tmp/en-US/xml/Common_Content/Feedback.xml =================================================================== --- docs/enterprise/trunk/Reference_Guide/tmp/en-US/xml/Common_Content/Feedback.xml 2008-11-12 22:44:10 UTC (rev 12288) +++ docs/enterprise/trunk/Reference_Guide/tmp/en-US/xml/Common_Content/Feedback.xml 2008-11-12 23:51:15 UTC (rev 12289) @@ -1,4 +1,4 @@ -<?xml version='1.0'?> +<?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> Modified: docs/enterprise/trunk/Reference_Guide/tmp/en-US/xml/Common_Content/Legal_Notice.xml =================================================================== --- docs/enterprise/trunk/Reference_Guide/tmp/en-US/xml/Common_Content/Legal_Notice.xml 2008-11-12 22:44:10 UTC (rev 12288) +++ docs/enterprise/trunk/Reference_Guide/tmp/en-US/xml/Common_Content/Legal_Notice.xml 2008-11-12 23:51:15 UTC (rev 12289) @@ -1,4 +1,4 @@ -<?xml version='1.0'?> +<?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> Modified: docs/enterprise/trunk/Reference_Guide/tmp/en-US/xml_tmp/Book_Info.xml =================================================================== --- docs/enterprise/trunk/Reference_Guide/tmp/en-US/xml_tmp/Book_Info.xml 2008-11-12 22:44:10 UTC (rev 12288) +++ docs/enterprise/trunk/Reference_Guide/tmp/en-US/xml_tmp/Book_Info.xml 2008-11-12 23:51:15 UTC (rev 12289) @@ -11,8 +11,8 @@ <productnumber>2.7</productnumber> <pubdate>Oct, 2007</pubdate> <isbn>N/A</isbn> + <issuenum>1</issuenum> - <abstract><para>This book is a JBoss Portal 2.7 Reference Guide.</para> </abstract>