| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8"> |
| <!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]--> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="generator" content="Asciidoctor 1.5.3"> |
| <title>Virgo Programmer Guide</title> |
| <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"> |
| <style> |
| /* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */ |
| /* Remove comment around @import statement below when using as a custom stylesheet */ |
| /*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/ |
| article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block} |
| audio,canvas,video{display:inline-block} |
| audio:not([controls]){display:none;height:0} |
| [hidden],template{display:none} |
| script{display:none!important} |
| html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%} |
| body{margin:0} |
| a{background:transparent} |
| a:focus{outline:thin dotted} |
| a:active,a:hover{outline:0} |
| h1{font-size:2em;margin:.67em 0} |
| abbr[title]{border-bottom:1px dotted} |
| b,strong{font-weight:bold} |
| dfn{font-style:italic} |
| hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0} |
| mark{background:#ff0;color:#000} |
| code,kbd,pre,samp{font-family:monospace;font-size:1em} |
| pre{white-space:pre-wrap} |
| q{quotes:"\201C" "\201D" "\2018" "\2019"} |
| small{font-size:80%} |
| sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline} |
| sup{top:-.5em} |
| sub{bottom:-.25em} |
| img{border:0} |
| svg:not(:root){overflow:hidden} |
| figure{margin:0} |
| fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em} |
| legend{border:0;padding:0} |
| button,input,select,textarea{font-family:inherit;font-size:100%;margin:0} |
| button,input{line-height:normal} |
| button,select{text-transform:none} |
| button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer} |
| button[disabled],html input[disabled]{cursor:default} |
| input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0} |
| input[type="search"]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box} |
| input[type="search"]::-webkit-search-cancel-button,input[type="search"]::-webkit-search-decoration{-webkit-appearance:none} |
| button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0} |
| textarea{overflow:auto;vertical-align:top} |
| table{border-collapse:collapse;border-spacing:0} |
| *,*:before,*:after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box} |
| html,body{font-size:100%} |
| body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto} |
| a:hover{cursor:pointer} |
| img,object,embed{max-width:100%;height:auto} |
| object,embed{height:100%} |
| img{-ms-interpolation-mode:bicubic} |
| .left{float:left!important} |
| .right{float:right!important} |
| .text-left{text-align:left!important} |
| .text-right{text-align:right!important} |
| .text-center{text-align:center!important} |
| .text-justify{text-align:justify!important} |
| .hide{display:none} |
| body{-webkit-font-smoothing:antialiased} |
| img,object,svg{display:inline-block;vertical-align:middle} |
| textarea{height:auto;min-height:50px} |
| select{width:100%} |
| .center{margin-left:auto;margin-right:auto} |
| .spread{width:100%} |
| p.lead,.paragraph.lead>p,#preamble>.sectionbody>.paragraph:first-of-type p{font-size:1.21875em;line-height:1.6} |
| .subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em} |
| div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr} |
| a{color:#2156a5;text-decoration:underline;line-height:inherit} |
| a:hover,a:focus{color:#1d4b8f} |
| a img{border:none} |
| p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility} |
| p aside{font-size:.875em;line-height:1.35;font-style:italic} |
| h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em} |
| h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0} |
| h1{font-size:2.125em} |
| h2{font-size:1.6875em} |
| h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em} |
| h4,h5{font-size:1.125em} |
| h6{font-size:1em} |
| hr{border:solid #ddddd8;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0} |
| em,i{font-style:italic;line-height:inherit} |
| strong,b{font-weight:bold;line-height:inherit} |
| small{font-size:60%;line-height:inherit} |
| code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)} |
| ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit} |
| ul,ol,ul.no-bullet,ol.no-bullet{margin-left:1.5em} |
| ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em} |
| ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit} |
| ul.square{list-style-type:square} |
| ul.circle{list-style-type:circle} |
| ul.disc{list-style-type:disc} |
| ul.no-bullet{list-style:none} |
| ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0} |
| dl dt{margin-bottom:.3125em;font-weight:bold} |
| dl dd{margin-bottom:1.25em} |
| abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help} |
| abbr{text-transform:none} |
| blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd} |
| blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)} |
| blockquote cite:before{content:"\2014 \0020"} |
| blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)} |
| blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)} |
| @media only screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2} |
| h1{font-size:2.75em} |
| h2{font-size:2.3125em} |
| h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em} |
| h4{font-size:1.4375em}} |
| table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede} |
| table thead,table tfoot{background:#f7f8f7;font-weight:bold} |
| table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left} |
| table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)} |
| table tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7} |
| table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6} |
| body{tab-size:4} |
| h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em} |
| h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400} |
| .clearfix:before,.clearfix:after,.float-group:before,.float-group:after{content:" ";display:table} |
| .clearfix:after,.float-group:after{clear:both} |
| *:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed} |
| pre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;text-rendering:optimizeSpeed} |
| .keyseq{color:rgba(51,51,51,.8)} |
| kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap} |
| .keyseq kbd:first-child{margin-left:0} |
| .keyseq kbd:last-child{margin-right:0} |
| .menuseq,.menu{color:rgba(0,0,0,.8)} |
| b.button:before,b.button:after{position:relative;top:-1px;font-weight:400} |
| b.button:before{content:"[";padding:0 3px 0 2px} |
| b.button:after{content:"]";padding:0 2px 0 3px} |
| p a>code:hover{color:rgba(0,0,0,.9)} |
| #header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em} |
| #header:before,#header:after,#content:before,#content:after,#footnotes:before,#footnotes:after,#footer:before,#footer:after{content:" ";display:table} |
| #header:after,#content:after,#footnotes:after,#footer:after{clear:both} |
| #content{margin-top:1.25em} |
| #content:before{content:none} |
| #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0} |
| #header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #ddddd8} |
| #header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #ddddd8;padding-bottom:8px} |
| #header .details{border-bottom:1px solid #ddddd8;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap} |
| #header .details span:first-child{margin-left:-.125em} |
| #header .details span.email a{color:rgba(0,0,0,.85)} |
| #header .details br{display:none} |
| #header .details br+span:before{content:"\00a0\2013\00a0"} |
| #header .details br+span.author:before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)} |
| #header .details br+span#revremark:before{content:"\00a0|\00a0"} |
| #header #revnumber{text-transform:capitalize} |
| #header #revnumber:after{content:"\00a0"} |
| #content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #ddddd8;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem} |
| #toc{border-bottom:1px solid #efefed;padding-bottom:.5em} |
| #toc>ul{margin-left:.125em} |
| #toc ul.sectlevel0>li>a{font-style:italic} |
| #toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0} |
| #toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none} |
| #toc li{line-height:1.3334;margin-top:.3334em} |
| #toc a{text-decoration:none} |
| #toc a:active{text-decoration:underline} |
| #toctitle{color:#7a2518;font-size:1.2em} |
| @media only screen and (min-width:768px){#toctitle{font-size:1.375em} |
| body.toc2{padding-left:15em;padding-right:0} |
| #toc.toc2{margin-top:0!important;background-color:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #efefed;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto} |
| #toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em} |
| #toc.toc2>ul{font-size:.9em;margin-bottom:0} |
| #toc.toc2 ul ul{margin-left:0;padding-left:1em} |
| #toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em} |
| body.toc2.toc-right{padding-left:0;padding-right:15em} |
| body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #efefed;left:auto;right:0}} |
| @media only screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0} |
| #toc.toc2{width:20em} |
| #toc.toc2 #toctitle{font-size:1.375em} |
| #toc.toc2>ul{font-size:.95em} |
| #toc.toc2 ul ul{padding-left:1.25em} |
| body.toc2.toc-right{padding-left:0;padding-right:20em}} |
| #content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px} |
| #content #toc>:first-child{margin-top:0} |
| #content #toc>:last-child{margin-bottom:0} |
| #footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em} |
| #footer-text{color:rgba(255,255,255,.8);line-height:1.44} |
| .sect1{padding-bottom:.625em} |
| @media only screen and (min-width:768px){.sect1{padding-bottom:1.25em}} |
| .sect1+.sect1{border-top:1px solid #efefed} |
| #content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400} |
| #content h1>a.anchor:before,h2>a.anchor:before,h3>a.anchor:before,#toctitle>a.anchor:before,.sidebarblock>.content>.title>a.anchor:before,h4>a.anchor:before,h5>a.anchor:before,h6>a.anchor:before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em} |
| #content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible} |
| #content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none} |
| #content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221} |
| .audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em} |
| .admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic} |
| table.tableblock>caption.title{white-space:nowrap;overflow:visible;max-width:0} |
| .paragraph.lead>p,#preamble>.sectionbody>.paragraph:first-of-type p{color:rgba(0,0,0,.85)} |
| table.tableblock #preamble>.sectionbody>.paragraph:first-of-type p{font-size:inherit} |
| .admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%} |
| .admonitionblock>table td.icon{text-align:center;width:80px} |
| .admonitionblock>table td.icon img{max-width:none} |
| .admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase} |
| .admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #ddddd8;color:rgba(0,0,0,.6)} |
| .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0} |
| .exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px} |
| .exampleblock>.content>:first-child{margin-top:0} |
| .exampleblock>.content>:last-child{margin-bottom:0} |
| .sidebarblock{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px} |
| .sidebarblock>:first-child{margin-top:0} |
| .sidebarblock>:last-child{margin-bottom:0} |
| .sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center} |
| .exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0} |
| .literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8} |
| .sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class="highlight"],.sidebarblock .listingblock pre[class^="highlight "],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1} |
| .literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;padding:1em;font-size:.8125em} |
| .literalblock pre.nowrap,.literalblock pre[class].nowrap,.listingblock pre.nowrap,.listingblock pre[class].nowrap{overflow-x:auto;white-space:pre;word-wrap:normal} |
| @media only screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}} |
| @media only screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}} |
| .literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)} |
| .listingblock pre.highlightjs{padding:0} |
| .listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px} |
| .listingblock pre.prettyprint{border-width:0} |
| .listingblock>.content{position:relative} |
| .listingblock code[data-lang]:before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:#999} |
| .listingblock:hover code[data-lang]:before{display:block} |
| .listingblock.terminal pre .command:before{content:attr(data-prompt);padding-right:.5em;color:#999} |
| .listingblock.terminal pre .command:not([data-prompt]):before{content:"$"} |
| table.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none} |
| table.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0;line-height:1.45} |
| table.pyhltable td.code{padding-left:.75em;padding-right:0} |
| pre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #ddddd8} |
| pre.pygments .lineno{display:inline-block;margin-right:.25em} |
| table.pyhltable .linenodiv{background:none!important;padding-right:0!important} |
| .quoteblock{margin:0 1em 1.25em 1.5em;display:table} |
| .quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em} |
| .quoteblock blockquote,.quoteblock blockquote p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify} |
| .quoteblock blockquote{margin:0;padding:0;border:0} |
| .quoteblock blockquote:before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)} |
| .quoteblock blockquote>.paragraph:last-child p{margin-bottom:0} |
| .quoteblock .attribution{margin-top:.5em;margin-right:.5ex;text-align:right} |
| .quoteblock .quoteblock{margin-left:0;margin-right:0;padding:.5em 0;border-left:3px solid rgba(0,0,0,.6)} |
| .quoteblock .quoteblock blockquote{padding:0 0 0 .75em} |
| .quoteblock .quoteblock blockquote:before{display:none} |
| .verseblock{margin:0 1em 1.25em 1em} |
| .verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility} |
| .verseblock pre strong{font-weight:400} |
| .verseblock .attribution{margin-top:1.25rem;margin-left:.5ex} |
| .quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic} |
| .quoteblock .attribution br,.verseblock .attribution br{display:none} |
| .quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)} |
| .quoteblock.abstract{margin:0 0 1.25em 0;display:block} |
| .quoteblock.abstract blockquote,.quoteblock.abstract blockquote p{text-align:left;word-spacing:0} |
| .quoteblock.abstract blockquote:before,.quoteblock.abstract blockquote p:first-of-type:before{display:none} |
| table.tableblock{max-width:100%;border-collapse:separate} |
| table.tableblock td>.paragraph:last-child p>p:last-child,table.tableblock th>p:last-child,table.tableblock td>p:last-child{margin-bottom:0} |
| table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede} |
| table.grid-all th.tableblock,table.grid-all td.tableblock{border-width:0 1px 1px 0} |
| table.grid-all tfoot>tr>th.tableblock,table.grid-all tfoot>tr>td.tableblock{border-width:1px 1px 0 0} |
| table.grid-cols th.tableblock,table.grid-cols td.tableblock{border-width:0 1px 0 0} |
| table.grid-all *>tr>.tableblock:last-child,table.grid-cols *>tr>.tableblock:last-child{border-right-width:0} |
| table.grid-rows th.tableblock,table.grid-rows td.tableblock{border-width:0 0 1px 0} |
| table.grid-all tbody>tr:last-child>th.tableblock,table.grid-all tbody>tr:last-child>td.tableblock,table.grid-all thead:last-child>tr>th.tableblock,table.grid-rows tbody>tr:last-child>th.tableblock,table.grid-rows tbody>tr:last-child>td.tableblock,table.grid-rows thead:last-child>tr>th.tableblock{border-bottom-width:0} |
| table.grid-rows tfoot>tr>th.tableblock,table.grid-rows tfoot>tr>td.tableblock{border-width:1px 0 0 0} |
| table.frame-all{border-width:1px} |
| table.frame-sides{border-width:0 1px} |
| table.frame-topbot{border-width:1px 0} |
| th.halign-left,td.halign-left{text-align:left} |
| th.halign-right,td.halign-right{text-align:right} |
| th.halign-center,td.halign-center{text-align:center} |
| th.valign-top,td.valign-top{vertical-align:top} |
| th.valign-bottom,td.valign-bottom{vertical-align:bottom} |
| th.valign-middle,td.valign-middle{vertical-align:middle} |
| table thead th,table tfoot th{font-weight:bold} |
| tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7} |
| tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold} |
| p.tableblock>code:only-child{background:none;padding:0} |
| p.tableblock{font-size:1em} |
| td>div.verse{white-space:pre} |
| ol{margin-left:1.75em} |
| ul li ol{margin-left:1.5em} |
| dl dd{margin-left:1.125em} |
| dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0} |
| ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em} |
| ul.unstyled,ol.unnumbered,ul.checklist,ul.none{list-style-type:none} |
| ul.unstyled,ol.unnumbered,ul.checklist{margin-left:.625em} |
| ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1em;font-size:.85em} |
| ul.checklist li>p:first-child>input[type="checkbox"]:first-child{width:1em;position:relative;top:1px} |
| ul.inline{margin:0 auto .625em auto;margin-left:-1.375em;margin-right:0;padding:0;list-style:none;overflow:hidden} |
| ul.inline>li{list-style:none;float:left;margin-left:1.375em;display:block} |
| ul.inline>li>*{display:block} |
| .unstyled dl dt{font-weight:400;font-style:normal} |
| ol.arabic{list-style-type:decimal} |
| ol.decimal{list-style-type:decimal-leading-zero} |
| ol.loweralpha{list-style-type:lower-alpha} |
| ol.upperalpha{list-style-type:upper-alpha} |
| ol.lowerroman{list-style-type:lower-roman} |
| ol.upperroman{list-style-type:upper-roman} |
| ol.lowergreek{list-style-type:lower-greek} |
| .hdlist>table,.colist>table{border:0;background:none} |
| .hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none} |
| td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em} |
| td.hdlist1{font-weight:bold;padding-bottom:1.25em} |
| .literalblock+.colist,.listingblock+.colist{margin-top:-.5em} |
| .colist>table tr>td:first-of-type{padding:0 .75em;line-height:1} |
| .colist>table tr>td:last-of-type{padding:.25em 0} |
| .thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd} |
| .imageblock.left,.imageblock[style*="float: left"]{margin:.25em .625em 1.25em 0} |
| .imageblock.right,.imageblock[style*="float: right"]{margin:.25em 0 1.25em .625em} |
| .imageblock>.title{margin-bottom:0} |
| .imageblock.thumb,.imageblock.th{border-width:6px} |
| .imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em} |
| .image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0} |
| .image.left{margin-right:.625em} |
| .image.right{margin-left:.625em} |
| a.image{text-decoration:none;display:inline-block} |
| a.image object{pointer-events:none} |
| sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super} |
| sup.footnote a,sup.footnoteref a{text-decoration:none} |
| sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline} |
| #footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em} |
| #footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em 0;border-width:1px 0 0 0} |
| #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;text-indent:-1.05em;margin-bottom:.2em} |
| #footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none} |
| #footnotes .footnote:last-of-type{margin-bottom:0} |
| #content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0} |
| .gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0} |
| .gist .file-data>table td.line-data{width:99%} |
| div.unbreakable{page-break-inside:avoid} |
| .big{font-size:larger} |
| .small{font-size:smaller} |
| .underline{text-decoration:underline} |
| .overline{text-decoration:overline} |
| .line-through{text-decoration:line-through} |
| .aqua{color:#00bfbf} |
| .aqua-background{background-color:#00fafa} |
| .black{color:#000} |
| .black-background{background-color:#000} |
| .blue{color:#0000bf} |
| .blue-background{background-color:#0000fa} |
| .fuchsia{color:#bf00bf} |
| .fuchsia-background{background-color:#fa00fa} |
| .gray{color:#606060} |
| .gray-background{background-color:#7d7d7d} |
| .green{color:#006000} |
| .green-background{background-color:#007d00} |
| .lime{color:#00bf00} |
| .lime-background{background-color:#00fa00} |
| .maroon{color:#600000} |
| .maroon-background{background-color:#7d0000} |
| .navy{color:#000060} |
| .navy-background{background-color:#00007d} |
| .olive{color:#606000} |
| .olive-background{background-color:#7d7d00} |
| .purple{color:#600060} |
| .purple-background{background-color:#7d007d} |
| .red{color:#bf0000} |
| .red-background{background-color:#fa0000} |
| .silver{color:#909090} |
| .silver-background{background-color:#bcbcbc} |
| .teal{color:#006060} |
| .teal-background{background-color:#007d7d} |
| .white{color:#bfbfbf} |
| .white-background{background-color:#fafafa} |
| .yellow{color:#bfbf00} |
| .yellow-background{background-color:#fafa00} |
| span.icon>.fa{cursor:default} |
| .admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default} |
| .admonitionblock td.icon .icon-note:before{content:"\f05a";color:#19407c} |
| .admonitionblock td.icon .icon-tip:before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111} |
| .admonitionblock td.icon .icon-warning:before{content:"\f071";color:#bf6900} |
| .admonitionblock td.icon .icon-caution:before{content:"\f06d";color:#bf3400} |
| .admonitionblock td.icon .icon-important:before{content:"\f06a";color:#bf0000} |
| .conum[data-value]{display:inline-block;color:#fff!important;background-color:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold} |
| .conum[data-value] *{color:#fff!important} |
| .conum[data-value]+b{display:none} |
| .conum[data-value]:after{content:attr(data-value)} |
| pre .conum[data-value]{position:relative;top:-.125em} |
| b.conum *{color:inherit!important} |
| .conum:not([data-value]):empty{display:none} |
| dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility} |
| h1,h2,p,td.content,span.alt{letter-spacing:-.01em} |
| p strong,td.content strong,div.footnote strong{letter-spacing:-.005em} |
| p,blockquote,dt,td.content,span.alt{font-size:1.0625rem} |
| p{margin-bottom:1.25rem} |
| .sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em} |
| .exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc} |
| .print-only{display:none!important} |
| @media print{@page{margin:1.25cm .75cm} |
| *{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important} |
| a{color:inherit!important;text-decoration:underline!important} |
| a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important} |
| a[href^="http:"]:not(.bare):after,a[href^="https:"]:not(.bare):after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em} |
| abbr[title]:after{content:" (" attr(title) ")"} |
| pre,blockquote,tr,img,object,svg{page-break-inside:avoid} |
| thead{display:table-header-group} |
| svg{max-width:100%} |
| p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3} |
| h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid} |
| #toc,.sidebarblock,.exampleblock>.content{background:none!important} |
| #toc{border-bottom:1px solid #ddddd8!important;padding-bottom:0!important} |
| .sect1{padding-bottom:0!important} |
| .sect1+.sect1{border:0!important} |
| #header>h1:first-child{margin-top:1.25rem} |
| body.book #header{text-align:center} |
| body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em 0} |
| body.book #header .details{border:0!important;display:block;padding:0!important} |
| body.book #header .details span:first-child{margin-left:0!important} |
| body.book #header .details br{display:block} |
| body.book #header .details br+span:before{content:none!important} |
| body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important} |
| body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always} |
| .listingblock code[data-lang]:before{display:block} |
| #footer{background:none!important;padding:0 .9375em} |
| #footer-text{color:rgba(0,0,0,.6)!important;font-size:.9em} |
| .hide-on-print{display:none!important} |
| .print-only{display:block!important} |
| .hide-for-print{display:none!important} |
| .show-for-print{display:inherit!important}} |
| </style> |
| </head> |
| <body class="article"> |
| <div id="header"> |
| <h1>Virgo Programmer Guide</h1> |
| <div id="toc" class="toc"> |
| <div id="toctitle">Table of Contents</div> |
| <ul class="sectlevel1"> |
| <li><a href="#_preface">Preface</a></li> |
| <li><a href="#_prerequisites">Prerequisites</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_runtime_environment">Runtime Environment</a></li> |
| <li><a href="#_references">References</a></li> |
| </ul> |
| </li> |
| <li><a href="#_introduction_to_the_virgo_for_apache_tomcat">Introduction to the Virgo for Apache Tomcat</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_overview">Overview</a></li> |
| <li><a href="#_what_is_the_virgo_for_apache_tomcat">What is the Virgo for Apache Tomcat?</a></li> |
| <li><a href="#_why_the_virgo_for_apache_tomcat">Why the Virgo for Apache Tomcat?</a></li> |
| </ul> |
| </li> |
| <li><a href="#_deployment_architecture">Deployment Architecture</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_supported_deployment_formats">Supported Deployment Formats</a></li> |
| <li><a href="#_dependency_types">Dependency Types</a></li> |
| <li><a href="#_regions">Regions</a></li> |
| <li><a href="#_a_guide_to_forming_bundles">A Guide to Forming Bundles</a></li> |
| </ul> |
| </li> |
| <li><a href="#_developing_applications">Developing Applications</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_anatomy_of_a_bundle">Anatomy of a Bundle</a></li> |
| <li><a href="#_creating_pars_and_web_applications">Creating PARs and Web Applications</a></li> |
| <li><a href="#_creating_plans">Creating Plans</a></li> |
| <li><a href="#_creating_and_using_configuration_artifacts">Creating and Using Configuration Artifacts</a></li> |
| <li><a href="#_using_spring_and_gemini_blueprint">Using Spring and Gemini Blueprint</a></li> |
| <li><a href="#_programmatic_access_to_the_servlet_context">Programmatic Access to the Servlet Context</a></li> |
| <li><a href="#_web_application_manifest_processing">Web Application Manifest Processing</a></li> |
| <li><a href="#_working_with_dependencies">Working with Dependencies</a></li> |
| <li><a href="#_application_trace">Application Trace</a></li> |
| <li><a href="#_application_versioning">Application Versioning</a></li> |
| </ul> |
| </li> |
| <li><a href="#_migrating_to_osgi">Migrating to OSGi</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_migrating_web_applications">Migrating Web Applications</a></li> |
| <li><a href="#_migrating_to_a_plan_or_a_par">Migrating to a Plan or a PAR</a></li> |
| </ul> |
| </li> |
| <li><a href="#_case_study_migrating_the_form_tags_sample_application">Case Study: Migrating the Form Tags Sample Application</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_overview_of_the_form_tags_sample_application">Overview of the Form Tags Sample Application</a></li> |
| <li><a href="#_form_tags_war">Form Tags WAR</a></li> |
| <li><a href="#_form_tags_shared_libraries_war">Form Tags Shared Libraries WAR</a></li> |
| <li><a href="#_form_tags_shared_services_war">Form Tags Shared Services WAR</a></li> |
| <li><a href="#_form_tags_par">Form Tags PAR</a></li> |
| <li><a href="#_constructing_the_par">Constructing the PAR</a></li> |
| <li><a href="#_summary_of_the_form_tags_migration">Summary of the Form Tags Migration</a></li> |
| <li><a href="#_form_tags_as_a_plan">Form Tags as a Plan</a></li> |
| </ul> |
| </li> |
| <li><a href="#_working_with_common_enterprise_libraries">Working with Common Enterprise Libraries</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_working_with_hibernate">Working with Hibernate</a></li> |
| <li><a href="#_working_with_datasources">Working with DataSources</a></li> |
| <li><a href="#_weaving_and_instrumentation">Weaving and Instrumentation</a></li> |
| <li><a href="#_jsp_tag_libraries">JSP Tag Libraries</a></li> |
| </ul> |
| </li> |
| <li><a href="#_known_issues">Known Issues</a> |
| <ul class="sectlevel2"> |
| <li><a href="#_jpa_entity_scanning">JPA Entity Scanning</a></li> |
| <li><a href="#__code_classnotfounderror_code_when_creating_a_proxy"><code>ClassNotFoundError</code> When Creating a Proxy</a></li> |
| <li><a href="#_creating_proxies_with_cglib_for_package_protected_types">Creating proxies with CGLIB for Package Protected Types</a></li> |
| <li><a href="#_virgo_jetty_server_restrictions">Virgo Jetty Server Restrictions</a></li> |
| <li><a href="#_default_web_application_bundle_headers">Default Web Application Bundle Headers</a></li> |
| <li><a href="#_hibernate_resolution_issue">Hibernate Resolution Issue</a></li> |
| <li><a href="#_scoping_and_substitutable_exports">Scoping and Substitutable Exports</a></li> |
| <li><a href="#_eclipselink_resolution_issue">EclipseLink Resolution Issue</a></li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div id="content"> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Ramnivas Laddad<br> |
| Colin Yates<br> |
| Sam Brannen<br> |
| Rob Harrop<br> |
| Christian Dupuis<br> |
| Andy Wilkinson<br> |
| Glyn Normington<br> |
| Steve Powell<br> |
| Christopher Frost<br> |
| Florian Waibel</p> |
| </div> |
| <div class="imageblock" style="float: right"> |
| <div class="content"> |
| <img src="assets/images/virgo-logo-small.png" alt="Eclipse Virgo"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Eclipse Virgo<br> |
| 3.7.1.RELEASE<br> |
| Copyright © 2009, 2011 VMware Inc. and others</p> |
| </div> |
| <hr> |
| <!-- toc disabled --> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_preface">Preface</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Increasing complexity in modern enterprise applications is a fact of life. |
| Developers not only have to deal with complex business logic, but also a myriad |
| of other concerns such as security, auditing, exposing business |
| functionality to external applications, and managing the evolution of |
| these concerns. The Spring Framework addresses these |
| needs by offering a Plain-Old Java Object (POJO) based solution that |
| lets you focus on your business logic.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Complex applications pose problems that go beyond using the right set of |
| technologies. You need to take into account other considerations such as |
| a simplified development process, easy deployment, monitoring deployed |
| applications, and managing changes in response to changing business needs. |
| This is where the Eclipse Virgo comes into play. It offers a simple yet |
| comprehensive platform to develop, deploy, and service enterprise |
| applications. In this Programmer Guide, we explore the runtime portions of the |
| Eclipse Virgo, the Virgo for Apache Tomcat, Virgo Jetty Server and the |
| Virgo Kernel, and learn how to develop applications to benefit from their |
| capabilities.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="title">For Virgo Kernel Programmers</div> |
| <div class="paragraph"> |
| <p>Although this guide is written primarily for Virgo for Apache Tomcat programmers, much of it is also useful for |
| Virgo Kernel programmers who should simply ignore the web-related sections.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="title">For Virgo Nano Programmers</div> |
| <div class="paragraph"> |
| <p>This guide is written primarily for Virgo for Apache Tomcat programmers. Although a base version of Virgo Nano, without the new provisioning |
| system, is used to build the Virgo for Apache Tomcat, much of this guide does not apply to Virgo Nano. The VN lacks regions support but has much |
| improved runtime footprint and startup time and also provides support for p2 provisioning. The Virgo Nano features are covered better in the |
| <a href="http://www.eclipse.org/virgo/documentation/virgo-documentation-$3.7.1.RELEASE/docs/virgo-user-guide/html/index.html">User Guide</a>.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a id="prerequisites-references"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_prerequisites">Prerequisites</h2> |
| <div class="sectionbody"> |
| <div class="sect2"> |
| <h3 id="_runtime_environment">Runtime Environment</h3> |
| <div class="paragraph"> |
| <p>Virgo requires Java SE 7 or later to be installed. Java is available from |
| <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Oracle</a> and elsewhere.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_references">References</h3> |
| <div class="paragraph"> |
| <p>To make effective use of the Virgo for Apache Tomcat, you should also refer to the following:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="http://www.eclipse.org/virgo/documentation/virgo-documentation-3.7.1.RELEASE/docs/virgo-user-guide/html/index.html">User Guide</a></p> |
| </li> |
| <li> |
| <p><a href="http://www.eclipse.org/virgo/documentation/virgo-documentation-3.6.4.RELEASE/docs/virgo-tooling-guide/html/index.html">Tooling Guide</a></p> |
| </li> |
| <li> |
| <p><a href="https://www.osgi.org/developer/specifications/">Blueprint Container Specification</a>(in the OSGi 4.2 and 5.0 Enterprise Specifications)</p> |
| </li> |
| <li> |
| <p><a href="https://docs.spring.io/spring/docs/4.2.9.RELEASE/spring-framework-reference/">Spring Framework 4.2.9.RELEASE Reference Documentation</a></p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_introduction_to_the_virgo_for_apache_tomcat">Introduction to the Virgo for Apache Tomcat</h2> |
| <div class="sectionbody"> |
| <div class="sect2"> |
| <h3 id="_overview">Overview</h3> |
| <div class="paragraph"> |
| <p>In this chapter, we provide an overview of the Virgo for Apache Tomcat focusing |
| on what it is, what benefits it provides to developers and administrators, |
| and why you should use it.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="introduction-what"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_what_is_the_virgo_for_apache_tomcat">What is the Virgo for Apache Tomcat?</h3> |
| <div class="paragraph"> |
| <p>The Virgo for Apache Tomcat, or VTS for short, is the runtime portion of the Eclipse Virgo. |
| It is a lightweight, modular, OSGi-based runtime that provides a complete packaged solution for developing, |
| deploying, and managing enterprise applications. |
| By leveraging several best-of-breed technologies and improving upon |
| them, the VTS offers a compelling solution to develop and deploy |
| enterprise applications.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="introduction-constituents"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_what_makes_up_the_virgo_for_apache_tomcat">What Makes up the Virgo for Apache Tomcat?</h4> |
| <div class="paragraph"> |
| <p>The Virgo for Apache Tomcat is built on top of the following core technologies:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="https://projects.spring.io/spring-framework/">Spring Framework</a>, obviously!</p> |
| </li> |
| <li> |
| <p><a href="http://tomcat.apache.org/">Tomcat</a> as the web container.</p> |
| </li> |
| <li> |
| <p><a href="http://www.osgi.org/Specifications/HomePage">OSGi R4.3</a>.</p> |
| </li> |
| <li> |
| <p><a href="http://www.eclipse.org/equinox/">Equinox</a> as the OSGi implementation.</p> |
| </li> |
| <li> |
| <p><a href="https://eclipse.org/gemini/blueprint/">Gemini Blueprint</a> for working with OSGi in a Spring application.</p> |
| </li> |
| <li> |
| <p><a href="http://www.eclipse.org/virgo/documentation/virgo-documentation-3.6.4.RELEASE/docs/virgo-tooling-guide/html/index.html">Tooling Guide</a> for developing applications.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Note, however, that the Virgo for Apache Tomcat isn’t just a combination |
| of these technologies. Rather, it integrates and extends these |
| technologies to provide many features essential for developing, |
| deploying, and managing today’s enterprise Java applications.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following diagram presents a high-level overview of the VTS’s architecture.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/introduction-architecture.png" alt="introduction architecture"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>At the heart of the Virgo for Apache Tomcat is the Virgo Kernel or VK. |
| The VK is an OSGi-based kernel that takes full advantage of the modularity |
| and versioning of the OSGi platform. The VK builds on a base version of Virgo Nano or VN and extends its capabilities for |
| provisioning and library management, as well as providing core functionality for the VTS. The VN maintains a minimal |
| runtime footprint and startup time. It builds on top of a pure Equinox, extending it with more sophisticated diagnostics and supportability functionality. |
| The VN supports full p2 provisioning. This feature is not included in the Virgo Nano Base that the VK is built on.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To maintain a minimal runtime footprint, OSGi bundles are installed on demand by the |
| VN. On subsequent restarts these core bundles are warm-started thus reducing the startup time. This allows for an application to be installed |
| into a running VTS and for its dependencies to be satisfied from an external repository. Not only |
| does this remove the need to manually install all your application dependencies, which would be tedious, but it also keeps memory usage to a minimum.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As shown in the figure, VK runs on top of VN that extends Equinox within a standard Java |
| Virtual Machine. Above the VK further layers contribute functionality |
| to the VTS. Such as management and web application support.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Version 3.7.1.RELEASE of the Virgo for Apache Tomcat supports <strong>bundle</strong>, |
| <strong>plan</strong>, <strong>PAR</strong>, <strong>configuration</strong>, |
| <strong>Web Application Bundle (WAB)</strong>, and <strong>WAR</strong> artifacts, which enable |
| you to build sophisticated web applications. This includes support for |
| standard Java EE WARs, "shared library" WARs, and "shared services" WARs, each of |
| which will be covered in greater detail in <a href="#architecture">Deployment Architecture</a>.</p> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Important</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>The Virgo Nano has a different provisioning system which isn’t included in the Virgo Nano Base on which the |
| VK and the VTS are built.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Version 3.7.1.RELEASE of the Virgo Nano supports <strong>bundle</strong>, |
| <strong>p2 feature</strong>, <strong>Web Application Bundle (WAB)</strong>, and <strong>WAR</strong> artifacts, which enable |
| you to build sophisticated web applications too, taking full advantage of p2’s dependency resolution, automated download and fail-early mechanics. |
| The Virgo Nano does NOT support <strong>plan</strong>, <strong>PAR</strong> or <strong>configuration</strong> artifacts. |
| New <strong>features</strong> are provisioned via <strong>update sites</strong> or <strong>p2 repositories</strong>. |
| Brief overview of p2 and it’s mechanics is available on <a href="http://bkapukaranov.wordpress.com/2011/07/12/rt-meets-p2/">this blog</a>. |
| The VN’s default web container implementation is Gemini Web.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="introduction-why"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_why_the_virgo_for_apache_tomcat">Why the Virgo for Apache Tomcat?</h3> |
| <div class="paragraph"> |
| <p>You could deploy a web application in a stand-alone servlet engine or application server. |
| Or you could even deploy directly in an OSGi container such as Equinox. However, |
| deploying in the Virgo for Apache Tomcat offers a number of key benefits that make it both more |
| appealing and more suitable for enterprise application development.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="introduction-unified-deployment"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_deployment_options_and_migration_paths">Deployment Options and Migration Paths</h4> |
| <div class="paragraph"> |
| <p>While many applications deployed in the Virgo for Apache Tomcat will take advantage |
| of OSGi capabilities, not all applications need such sophistication. |
| For example, development teams may initially choose to continue packaging |
| existing web applications as standard WAR files and then gradually migrate |
| toward a fully OSGi-based packaging and deployment model. The Virgo for Apache Tomcat |
| makes such migrations easy for developers by supporting multiple packaging |
| and deployment formats. These formats and migration strategies are discussed |
| in greater detail in <a href="#migrating-to-osgi">Migrating to OSGi</a> and |
| <a href="#formtags-case-study">Case Study: Migrating the Form Tags Sample Application</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="introduction-simplified-deployment"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_simplified_development_and_deployment_of_osgi_based_applications">Simplified Development and Deployment of OSGi-based Applications</h4> |
| <div class="paragraph"> |
| <p>Prior to the release of the Virgo for Apache Tomcat, developing and deploying OSGi |
| applications involved inherent complexity such as:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Obtaining OSGi bundles for popular Java libraries:</strong> |
| For optimal benefits, every technology you use in an OSGi application must |
| be packaged as OSGi bundles. Sometimes, this involves manually converting |
| JAR files into bundles and making sure that any libraries needed by those |
| bundles are also available as OSGi bundles. The <a href="http://www.eclipse.org/ebr">EBR</a> is a good source of |
| popular pre-bundled libraries.</p> |
| </li> |
| <li> |
| <p><strong>Package management complexity:</strong> |
| OSGi bundles use other bundles through <code>Import-Package</code> manifest headers. |
| Many applications use a set of common technologies (e.g., an ORM solution, |
| a web framework, etc.). Combining these two characteristics leads to duplicated |
| configuration in the form of repeated and verbose <code>Import-Package</code> statements.</p> |
| </li> |
| <li> |
| <p><strong>Lack of application-level isolation:</strong> |
| In OSGi everything is a bundle, and all bundles share the same OSGi Service Registry. |
| To highlight how conflicts can arise between applications and their services in this |
| shared service registry, consider the following scenarios.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Application <code>A</code> is comprised of bundles <code>B</code> and <code>C</code>. |
| In a standard OSGi environment, if you attempt to install two instances of the same |
| version of application <code>A</code> (i.e., two sets of bundles <code>B</code> and |
| <code>C</code>), a clash will occur, because you cannot deploy multiple bundles with |
| the same <code>Bundle-SymbolicName</code> and <code>Bundle-Version</code> combination.</p> |
| </li> |
| <li> |
| <p>Application <code>A1</code> is comprised of bundles <code>B1</code> and <code>C1</code>. |
| Similarly, application <code>A2</code> is comprised of bundles <code>B2</code> and <code>C2</code>. |
| Each bundle has a unique combination of <code>Bundle-SymbolicName</code> and <code>Bundle-Version</code>. |
| Bundles <code>B1</code> and <code>B2</code> both export service <code>S</code> which |
| is imported by both <code>C1</code> and <code>C2</code>. In contrast to the previous |
| example, there is no conflict resulting from duplicate |
| <code>Bundle-SymbolicName</code>/<code>Bundle-Version</code> combinations; however, |
| there is a clash for the exported service <code>S</code>. |
| Which service <code>S</code> will bundles <code>C1</code> and <code>C2</code> end up |
| using once they are installed? |
| Assuming bundles <code>B1</code> and <code>C1</code> are intended to work together, |
| you would not want bundle <code>C1</code> to get a reference to service <code>S</code> |
| from bundle <code>B2</code>, because it is installed in a different logical application. |
| On the contrary, you typically want bundle <code>C1</code> to get a reference to |
| service <code>S</code> exported by bundle <code>B1</code>, but in a standard OSGi environment |
| this may not be the case.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Furthermore, since standard OSGi does not define a notion of an application as a set of bundles, |
| you cannot deploy or undeploy an application and its constituent bundles as a single unit.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Virgo for Apache Tomcat introduces a number of features to solve these issues:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>A full set of OSGi bundles for many popular Java libraries to get you |
| started quickly with creating OSGi applications.</p> |
| </li> |
| <li> |
| <p>An OSGi library concept that obviates the need to |
| duplicate verbose <code>Import-Package</code> statements.</p> |
| </li> |
| <li> |
| <p>The PAR packaging format which offers |
| application-level isolation and deployment.</p> |
| </li> |
| <li> |
| <p>The concept of a plan, which is an XML file that lists a collection of bundles that Virgo for Apache Tomcat should load together as a single application. Conceptually, plans are very like PARs, except that a plan describes the contents of the application rather than a PAR that actually contains them.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a id="introduction-diagnostics"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_enhanced_diagnostics_during_deployment_and_in_production">Enhanced Diagnostics During Deployment and in Production</h4> |
| <div class="paragraph"> |
| <p>Identifying why an application won’t deploy or which particular library |
| dependencies are unsatisfied is the cause of many headaches! |
| Similarly, production time errors that don’t identify the root cause are |
| all too familiar to Java developers. The VTS was designed from the |
| ground up to enable tracing and First Failure Data Capture (FFDC) that |
| empower developers with precise information at the point of failure to |
| fix the problem quickly.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="architecture"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_deployment_architecture">Deployment Architecture</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The Virgo for Apache Tomcat offers several choices when it comes to deploying applications. Each |
| choice offers certain advantages, and it is important to understand those in order to make |
| the right choice for your application. In this chapter, we take a closer look at the choices |
| offered, compare them, and provide guidelines in choosing the right one based on your |
| specific needs.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The VTS supports standard self-contained WAR files thus allowing you to |
| use the Virgo for Apache Tomcat as an enhanced web server. The VTS also supports the |
| <strong>Shared Libraries</strong> WAR format which allows for slimmer WAR files that |
| depend on OSGi bundles instead of including JAR files inside the WAR. The <strong>Shared |
| Services</strong> WAR format allows developers to further reduce the complexity of |
| standard WARs by deploying services and infrastructure bundles alongside the WAR. A shared |
| services WAR will then consume the services published by those bundles. To complete the |
| picture, the VTS supports the new OSGi-standard <strong>Web Application |
| Bundle</strong> deployment format for web applications that builds on the benefits |
| provided by a shared services WAR. In addition to this, VTS provides |
| additional conveniences for developing and deploying Spring MVC-based web applications.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For applications consisting of multiple bundles and web applications, plans and the PAR |
| format are the primary deployment models that take advantage of OSGi capabilities. We will |
| explore all of these formats and their suitability later in this guide.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="architecture-deployment-formats"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_supported_deployment_formats">Supported Deployment Formats</h3> |
| <div class="paragraph"> |
| <p>The Virgo for Apache Tomcat supports applications packaged in the following formats:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p><a href="#architecture-raw-osgi-bundles">Raw OSGi Bundles</a></p> |
| </li> |
| <li> |
| <p><a href="#architecture-wars">Java EE WAR</a></p> |
| </li> |
| <li> |
| <p><a href="#architecture-war-gemini">Web Application Bundles</a></p> |
| </li> |
| <li> |
| <p><a href="#architecture-pars">PARs</a></p> |
| </li> |
| <li> |
| <p><a href="#architecture-plans">Plans</a></p> |
| </li> |
| <li> |
| <p><a href="#architecture-configurations">Configurations</a></p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>When you deploy an application to the VTS, each deployment artifact |
| (e.g., a single bundle, WAR, PAR, or plan) passes through a deployment pipeline. This |
| deployment pipeline is responsible for processing applications of certain types (i.e., |
| application type). The 3.7.1.RELEASE release of the VTS natively |
| supports deployers analogous to each of the aforementioned packaging options.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Let’s take a closer look now at each of the supported deployment and packaging |
| options to explore which one is best suited to your application.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="architecture-raw-osgi-bundles"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_raw_osgi_bundles">Raw OSGi Bundles</h4> |
| <div class="paragraph"> |
| <p>At its core, the Virgo for Apache Tomcat is an OSGi container. Thus any OSGi-compliant |
| bundle can be deployed directly on the VTS unmodified. You’ll |
| typically deploy an application as a single bundle or a set of stand-alone bundles |
| if you’d like to publish or consume services globally within the container via |
| the OSGi Service Registry.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="architecture-wars"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_war_deployment_formats">WAR Deployment Formats</h4> |
| <div class="paragraph"> |
| <p>For Web Application Archives (WAR), the Virgo for Apache Tomcat provides support for the |
| following three formats.</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p><a href="#architecture-standard-war">Standard WAR</a></p> |
| </li> |
| <li> |
| <p><a href="#architecture-shared-libraries-war">Shared Libraries WAR</a></p> |
| </li> |
| <li> |
| <p><a href="#architecture-shared-services-war">Shared Services WAR</a></p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>Each of these formats plays a distinct role in the incremental migration path |
| from a standard Java EE WAR to an OSGi-ified web application.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="architecture-standard-war"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_standard_war">Standard WAR</h4> |
| <div class="paragraph"> |
| <p>Standard WAR files are supported directly in the VTS. At |
| deployment time, the WAR file is transformed into an OSGi bundle and installed |
| into Tomcat. All the standard WAR contracts are honoured, and your existing WAR |
| files should just drop in and deploy without change. Support for standard, |
| unmodified WAR files allows you to try out the Virgo for Apache Tomcat on your existing |
| web applications and then gradually migrate toward the <strong>Shared |
| Libraries WAR</strong> and <strong>Shared Services WAR</strong> formats.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In addition to the standard support for WARs that you would expect from |
| Tomcat, the VTS also enables the following features:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Spring-driven load-time weaving (see Section 6.8.4, “Load-time weaving |
| with AspectJ in the Spring Framework"). |
| Diagnostic information such as FFDC (first failure data capture)</p> |
| </li> |
| <li> |
| <p>The main benefit of this application style is familiarity — developers know |
| how to create a WAR file! You can take advantage of the |
| VTS’s added feature set without modifying the |
| application. The application can also be deployed on other Servlet containers or |
| Java EE application servers.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>You may choose this application style if the application is fairly simple and |
| small. You may also prefer this style even for large and complex applications as |
| a starting point and migrate to the other styles over time as discussed in <a href="#migrating-to-osgi">Migrating to OSGi</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="architecture-shared-libraries-war"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_shared_libraries_war">Shared Libraries WAR</h4> |
| <div class="paragraph"> |
| <p>If you have experience with developing and packaging web applications using |
| the standard WAR format, you’re certainly familiar with the pains of |
| library bloat. So, unless you’re installing shared libraries in a common |
| library folder for your Servlet container, you have to pack all JARs required by |
| your web application in <code>/WEB-INF/lib</code>. Prior to the release of |
| the Virgo for Apache Tomcat, such library bloat has essentially been the norm for web |
| applications, but now there is a better solution! The Shared Libraries WAR |
| format reduces your application’s deployment footprint and eradicates |
| library bloat by allowing you to declare dependencies on libraries via standard |
| OSGi manifest headers such as <code>Import-Package</code> and <code>Require-Bundle</code> . The VTS provides additional |
| support for simplifying dependency management via the <code>Import-Library</code> and <code>Import-Bundle</code> manifest headers |
| which are essentially macros that get expanded into OSGi-compliant <code>Import-Package</code> statements.</p> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Tip</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>For detailed information on which libraries are already available, check |
| out the <a href="http://www.eclipse.org/ebr">EBR</a>.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a id="architecture-shared-services-war"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_shared_services_war">Shared Services WAR</h4> |
| <div class="paragraph"> |
| <p>Once you’ve begun taking advantage of declarative dependency management |
| with a Shared Libraries WAR, you’ll likely find yourself wanting to take |
| the next step toward reaping further benefits of an OSGi container: sharing |
| services between your OSGi-compliant bundles and your web applications. By |
| building on the power and simplicity of Gemini Blueprint, the <strong>Shared Services |
| WAR</strong> format puts the OSGi Service Registry at your finger tips. As |
| a best practice you’ll typically publish services from your domain, |
| service, and infrastructure bundles via <code><osgi:service …​></code> and then consume them in your web application’s |
| ApplicationContext via <code><osgi:reference …​ ></code>. Doing so |
| promotes programming to interfaces and allows you to completely decouple your |
| web-specific deployment artifacts from your domain model, service layer, etc., |
| and that’s certainly a step in the right direction. Of the three supported |
| WAR deployment formats, the Shared Services WAR is by far the most attractive in |
| terms of modularity and reduced overall footprint of your web applications.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="architecture-war-gemini"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_wars_and_the_gemini_web_container">WARs and the Gemini Web Container</h4> |
| <div class="paragraph"> |
| <p>Virgo for Apache Tomcat fully supports the OSGi Web Applications standard. Using the |
| reference implementation from Gemini Web that was developed by SpringSource from |
| an offshoot of the original VTS codebase. This RI is now fully |
| integrated in VTS as the basis of the support for web |
| application deployment.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The OSGi Web Applications specification introduces the concept of a <strong>Web |
| Application Bundle</strong>, which is a WAR that is also a bundle. The |
| specification defines how WAR files are transformed into bundles automatically |
| as needed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You can find an introduction to the Web Container in blog entries written by |
| the Virgo team <a href="http://blog.springsource.com/2009/05/27/introduction-to-the-osgi-web-container/">here</a> |
| and <a href="http://blog.springsource.com/2009/06/01/what-the-osgi-web-container-means-for-dm-server/">here</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="architecture-war-gemini-extensions"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_extensions_to_the_web_container">Extensions to the Web Container</h4> |
| <div class="paragraph"> |
| <p>Virgo for Apache Tomcat provides a variety of extensions to the Web Container that |
| allow you to construct sophisticated applications. The table below |
| summarises the extensions that are available or in development.</p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Feature</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Instrumentable ClassLoaders</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">All web bundle ClassLoaders are |
| instrumentable by Spring’s load-time weaving infrastructure.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Support for exploded bundles/WARs</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Bundles/WARs in directory form can |
| be deployed as Web Application Bundles</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Support for scanning TLDs in dependencies</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">As per the Web Application |
| specification, all TLDs located inside a web bundle are located using |
| the rules defined in the JSP 2.1 specification. In |
| VTS, the dependencies of a Web Application |
| Bundle are also scanned for TLDs following the rules outlined in JSP 2.1</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a id="architecture-pars"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_par">PAR</h4> |
| <div class="paragraph"> |
| <p>A PAR is a standard JAR which contains all of the modules of your application |
| (e.g., service, domain, and infrastructure bundles as well as a WAR or web module |
| for web applications) in a single deployment unit. This allows you to deploy, |
| refresh, and undeploy your entire application as a single entity. If you are |
| familiar with Java EE, it is worth noting that a PAR can be considered a replacement |
| for an EAR (Enterprise Archive) within the context of an OSGi container. As an added |
| bonus, modules within a PAR can be refreshed independently and on-the-fly, for |
| example via the Virgo Eclipse IDE Tooling (see the Virgo Tools Guide).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Many of the benefits of the PAR format are due to the underlying OSGi |
| infrastructure, including:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Fundamentally modularized applications: instead of relying on fuzzy |
| boundaries between logical modules in a monolithic application, this |
| style promotes physically separated modules in the form of OSGi bundles. |
| Then each module may be developed separately, promoting parallel |
| development and loose coupling.</p> |
| </li> |
| <li> |
| <p>Robust versioning of various modules: the versioning capability |
| offered by OSGi is much more comprehensive than alternatives. Each |
| module can specify a version range for each of its dependencies. Bundles |
| are isolated from each other in such a way that multiple versions of a |
| bundle may be used simultaneously in an application.</p> |
| </li> |
| <li> |
| <p>Improved manageability: each bundle may be deployed or undeployed in |
| a running application. This allows modifying the existing application to |
| fix bugs, improve performance, and even to add new features without |
| having to restart the application.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Furthermore, PARs scope the bundles of your application within the |
| VTS. Scoping provides both a physical and logical application |
| boundary, effectively shielding the internals of your application from other PARs |
| deployed within the VTS. This means your application doesn’t |
| have to worry about clashing with other running applications (e.g., in the OSGi |
| Service Registry). You get support for load-time weaving, classpath scanning, |
| context class loading, etc., and the VTS does the heavy lifting for |
| you to make all this work seamlessly in an OSGi environment. If you want to take |
| full advantage of all that the Virgo for Apache Tomcat and OSGi have to offer, packaging and |
| deploying your applications as a PAR is a good choice, although plans are an even |
| better one, as described in the next section.</p> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Tip</div> |
| </td> |
| <td class="content"> |
| <div class="title">OSGi != multiple JARs</div> |
| <div class="paragraph"> |
| <p>Note that while physically separated modules can, in theory, be implemented |
| simply using multiple JARs, complex versioning requirements often make this |
| impractical. For example, consider the situation depicted in the diagram below.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Bundle A depends on version <code>1.0.0</code> of bundle <code>B</code> and version <code>2.0.0</code> of bundle <code>C</code>.</p> |
| </li> |
| <li> |
| <p>Bundle B depends on version <code>1.0.0</code> of bundle <code>C</code>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Suppose that versions <code>1.0.0</code> and <code>2.0.0</code> of bundle <code>C</code> are neither |
| backward nor forward compatible. Traditional monolithic applications cannot |
| handle such situations: either bundle <code>A</code> or bundle <code>B</code> would need reworking which |
| undermines truly independent development. OSGi’s versioning scheme enables |
| this scenario to be implemented in a robust manner. If it is desirable to rework |
| the application to share a single version of <code>C</code>, then this can be planned in and |
| is not forced.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="assets/images/architecture-bundle-versioning.png" alt="architecture bundle versioning"> |
| </div> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a id="architecture-plans"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_plans">Plans</h4> |
| <div class="paragraph"> |
| <p>A plan is similar to a PAR in that it encapsulates all of the artifacts of your |
| application in a single deployment unit. The main difference, however, is that a |
| plan is simply an XML file that lists the artifacts of your application; a PAR, by |
| contrast, is an actual JAR file that physically contains the artifacts. Just like a |
| PAR, you deploy, refresh, and undeploy a plan as a single entity. We highly |
| recommends the use of plans for creating applications.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When you create a plan, you can specify that the included bundles and services |
| are in a scope that isolates them from the rest of Virgo for Apache Tomcat and its |
| deployments. This scoping ensures that the bundles wire to each other and see each |
| other’s services in preference to services from outside the scope. Scoping |
| also prevents application code from leaking into the global scope or scope of |
| another application. In addition, a plan can link the lifecycle of a group of |
| bundles together atomically, which ensures that start, stop, and uninstall |
| events on a single artifact in the plan are escalated to all artifacts in the plan. |
| You can, however, disable both of these features by simply setting an attribute in |
| the plan.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The general benefits of using plans are similar to those of using PARs; see <a href="#architecture-pars">PAR</a> for details. Plans offer added benefits, |
| however, such as the ability to control the deployment order of your application: |
| the order in which you list artifacts in the plan’s XML file is the order in |
| which VTS deploys them. Additionally, because plans specify the |
| artifacts that make up an application by reference, it is easier to share artifacts |
| between plans as well as update individual parts of a plan without having to |
| physically repackage (re-JAR) it.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="architecture-configurations"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_configurations">Configurations</h4> |
| <div class="paragraph"> |
| <p>A Configuration is simply a Java properties file. When deployed it will be |
| recognised by the deployer and installed in to <strong>Configuration |
| Admin</strong> for later use by your applications. VTS supports |
| both singleton (ManagedService) and factory (ManagedServiceFactory) configurations. |
| (see section 104.6 in the Compendium Specification)</p> |
| </div> |
| <div class="paragraph"> |
| <p>For a singleton configuration the name that it will be installed under is its filename |
| minus the <code>.properties</code> extension. Factory Configuration is supported by |
| specifying the <strong>service.factoryPid</strong> property. In this case the actual PID will |
| be created by <strong>Configuration Admin</strong> (see section 104.6 in the |
| Compendium Specification).</p> |
| </div> |
| <div class="paragraph"> |
| <p>How to consume configuration data is discussed <a href="#developing-applications-configuration-artifacts">later</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="architecture-dependency-types"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_dependency_types">Dependency Types</h3> |
| <div class="paragraph"> |
| <p>In an OSGi environment, there are two kinds of dependencies between various bundles: |
| <strong>type</strong> dependency and <strong>service</strong> dependency.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Type dependency</strong>: A bundle may depend on a |
| type exported by another bundle thus creating a type dependency. Type |
| dependencies are managed through <code>Import-Package</code> and |
| <code>Export-Package</code> directives in the OSGi manifest. This |
| kind of dependency is similar to a JAR file using types in other JAR files |
| from the classpath. However, as we’ve seen earlier, there are |
| significant differences.</p> |
| </li> |
| <li> |
| <p><strong>Service dependency</strong>: A bundle may also |
| publish services (preferably using Gemini Blueprint), and other bundles may consume |
| those services. If two bundles depend on the same service, both will be |
| communicating effectively to the same object. More specifically, any state |
| for that service will be shared between all the clients of that service. |
| This kind of arrangement is similar to the commonly seen client-server |
| interaction through mechanisms such as RMI or Web Services.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_regions">Regions</h3> |
| <div class="paragraph"> |
| <p>Conceptually, the Eclipse Virgo can be divided into two separate subsystems, called Regions. This |
| provides a way to keep the Virgo Kernel separate from user applications. Read more about Regions |
| and the two in Virgo in the <a href="http://www.eclipse.org/virgo/documentation/virgo-documentation-3.7.1.RELEASE/docs/virgo-user-guide/html/index.html">User Guide</a> |
| concepts section.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="architecture-forming-bundles"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_a_guide_to_forming_bundles">A Guide to Forming Bundles</h3> |
| <div class="paragraph"> |
| <p>So what makes an application suitable for deployment on the Virgo for Apache Tomcat? Since |
| OSGi is at the heart of the VTS, modular applications consisting of |
| bundles, which each represent distinct functionality and well-defined boundaries, can |
| take maximum advantage of the OSGi container’s capabilities. The core ideas behind |
| forming bundles require following good software engineering practices: separation of |
| concerns, loose coupling, and communication through clear interfaces. In this section, |
| we look at a few approaches that you may use to create modular applications for |
| Virgo for Apache Tomcat deployment. Please consider the following discussion as guidelines and |
| not as rules.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Bundles can be formed along horizontal slices of layering and vertical slices of |
| function. The objective is to enable independent development of each bundle and minimize |
| the skills required to develop each bundle.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, an application could have the following bundles: |
| <strong>infrastructure</strong>, <strong>domain</strong>, |
| <strong>repository</strong>, <strong>service</strong>, and |
| <strong>web</strong> as shown in the following diagram.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="assets/images/bundle-dependencies-layers.png" alt="bundle dependencies layers"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Each bundle consists of types appropriate for that layer and exports |
| packages and services to be used by other layers. Let’s examine each bundle in |
| more detail:</p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 1. Bundles across layers</caption> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Bundles</th> |
| <th class="tableblock halign-left valign-top">Imported Packages</th> |
| <th class="tableblock halign-left valign-top">Exported Packages</th> |
| <th class="tableblock halign-center valign-top">Consumed Services</th> |
| <th class="tableblock halign-center valign-top">Published Services</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Infrastructure</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Third-party libraries</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Infrastructure interfaces</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">None</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">None</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Domain</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Depends: for example, |
| if JPA is used to |
| annotate persistent |
| types, then JPA |
| packages.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Public domain types</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">None</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">None</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Web</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Domain, Service</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">None</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">Service beans</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">None</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Service</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Domain, |
| Infrastructure, |
| Repository</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Service interfaces</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">Repository beans</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">Service beans</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Repository</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Domain, |
| Third-party libraries, |
| ORM bundles, etc.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Repository interfaces</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">DataSources, |
| ORM session/entity managers, |
| etc.</p></td> |
| <td class="tableblock halign-center valign-top"><p class="tableblock">Repository beans</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Within each layer, you may create bundles for each subsystem representing a vertical |
| slice of business functionality. For example, as shown in the following figure, the |
| service layer is divided into two bundles each representing separate business |
| functions. |
| <span class="image"><img src="assets/images/bundle-dependencies-verticals.png" alt="bundle dependencies verticals"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>You can similarly separate the repositories, domain classes, and web controllers |
| based on the business role they play.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_developing_applications">Developing Applications</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Applications that take advantage of the OSGi capabilities of Virgo |
| are typically comprised of multiple bundles. Each bundle may have dependencies on |
| other bundles. Furthermore, each bundle exposes only certain packages and |
| services. In this chapter, we look at how to create bundles, import and export |
| appropriate functionality, and create artifacts to deploy web applications on the Virgo for Apache Tomcat.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-bundle"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_anatomy_of_a_bundle">Anatomy of a Bundle</h3> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Tip</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>This is an abbreviated introduction to OSGi bundles. Please refer to the <a href="https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html">Eclipse Gemini Blueprint Reference Guide</a> for full details.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>An OSGi bundle is simply a jar file with metadata that describe |
| additional characteristics such as version and imported and exported packages.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A bundle exports types and publishes services to be used by other bundles:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Types</strong>: via the OSGi <code>Export-Package</code> directive,</p> |
| </li> |
| <li> |
| <p><strong>Services</strong>: via Gemini Blueprint’s <code><service …​ ></code> XML namespace element.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>A bundle may import types and services exported by other bundles:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Types</strong>: via the OSGi <code>Import-Package</code> directive,</p> |
| </li> |
| <li> |
| <p><strong>Services</strong>: via Gemini Blueprint’s <code><reference …​ ></code> XML namespace element.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Let’s see an example from the PetClinic sample application. The following listing shows the |
| <code>MANIFEST.MF</code> file for the <code>org.springframework.petclinic.infrastructure.hsqldb</code> bundle.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="title">MANIFEST.MF</div> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">Manifest-Version: 1.0 |
| Bundle-ManifestVersion: 2 |
| Bundle-Name: PetClinic HSQL Database Infrastructure |
| Bundle-SymbolicName: org.springframework.petclinic.infrastructure.hsqldb |
| Bundle-Version: 1.0 |
| Import-Library: org.springframework.spring;version="[2.5,2.6]" |
| Import-Bundle: com.springsource.org.apache.commons.dbcp;version="[1.2.2.osgi,1.2.2.osgi]", |
| com.springsource.org.hsqldb;version="[1.8.0.9,1.8.0.9]" |
| Import-Package: javax.sql |
| Export-Package: org.springframework.petclinic.infrastructure</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>org.springframework.petclinic.infrastructure.hsqldb</code> bundle expresses its dependencies on |
| the <code>javax.sql</code> package, the Commons DBCP and HSQLDB bundles, and the Spring library (we will examine |
| the details of the library artifact in <a href="#developing-applications-defining-libraries">Defining Libraries</a>. The Commons DBCP |
| bundle is imported at a version of exactly <code>1.2.2.osgi</code> and the HSQLDB bundle is imported at a version of exactly |
| <code>1.8.0.9</code>. The Spring library is imported at a version between <code>2.5</code> inclusive and <code>2.6</code> exclusive.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that you do not specify the bundle that will provide the imported packages. |
| Virgo will examine the available bundles and satisfy the required dependencies.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following <code>osgi-context.xml</code> file from the PetClinic sample’s |
| <code>org.springframework.petclinic.repository.jdbc</code> bundle declares a service published by the bundle and |
| references a service published by another bundle.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="title">osgi-context.xml</div> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> |
| <beans:beans xmlns="http://www.springframework.org/schema/osgi" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xmlns:beans="http://www.springframework.org/schema/beans" |
| xsi:schemaLocation="http://www.springframework.org/schema/osgi |
| http://www.springframework.org/schema/osgi/spring-osgi.xsd |
| http://www.springframework.org/schema/beans |
| http://www.springframework.org/schema/beans/spring-beans.xsd"> |
| |
| <service id="osgiClinic" ref="clinic" interface="org.springframework.petclinic.repository.Clinic" /> |
| <reference id="dataSource" interface="javax.sql.DataSource"/> |
| |
| </beans:beans></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>service</code> element publishes the <code>clinic</code> bean |
| (a regular Spring bean declared in the <code>module-context.xml</code> file) and specifies |
| <code>org.springframework.petclinic.repository.Clinic</code> as the type |
| of the published service.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>reference</code> elements define a <code>dataSource</code> bean that references |
| a service published by another bundle with a an interface type of <code>javax.sql.DataSource</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-packaging"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_creating_pars_and_web_applications">Creating PARs and Web Applications</h3> |
| <div class="paragraph"> |
| <p>Virgo supports two OSGi-oriented ways of packaging applications: the PAR format |
| and application bundles (including web bundles). The VTS also supports three |
| distinct WAR deployment and packaging formats: standard Java EE WAR, Shared Libraries WAR, Shared Services WAR.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Virgo also supports plans as a way to describe an application. This method is similar to a PAR |
| in that it encapsulates all the artifacts of an application as a single unit, but differs in that a plan simply |
| lists the bundles in an XML file rather than packaging all the bundles in a single JAR file. The use of plans |
| offers additional benefits to using PARs; for this reason, we recommend their use. For details, see |
| <a href="#developing-applications-plans">Creating Plans</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-packaging-par"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_pars">PARs</h4> |
| <div class="paragraph"> |
| <p>An OSGi application is packaged as a JAR file, with extension <code>.par</code>. A PAR artifact offers several benefits:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>A PAR file has an application name, version, symbolic name, and description.</p> |
| </li> |
| <li> |
| <p>The artifacts of a PAR file are scoped so that they cannot |
| be shared accidentally by other applications. The scope forms a boundary for automatic |
| propagation of load time weaving and bundle refresh. |
| See <a href="#developing-applications-plans-scoping">Plans and Scoping</a> for more on scoping.</p> |
| </li> |
| <li> |
| <p>Since a PAR is scoped, its artifacts have their exported packages imported by the |
| synthetic context bundle which is used for thread context class loading. So, |
| for example, hibernate will be able to load classes of any of the exported |
| packages of the bundles in a PAR file using the thread context class loader.</p> |
| </li> |
| <li> |
| <p>A PAR file is visible to management interfaces.</p> |
| </li> |
| <li> |
| <p>A PAR file can be undeployed and redeployed as a unit.</p> |
| </li> |
| <li> |
| <p>A PAR file is <strong>atomic</strong> in that it ties together the lifecycle of its artifacts. If you start, stop, or uninstall |
| one of a PAR’s artifacts, Virgo escalates the operation to the whole PAR file. |
| So Virgo prevents artifacts of a PAR from being in inconsistent states. |
| For example, if one artifact should fail to start, then Virgo stops all artifacts in the PAR.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>See <a href="#developing-applications-plans-scoping">Plans and Scoping</a> for more information on scoping.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A PAR includes one or more application bundles and its manifest specifies the following |
| manifest headers:</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-packaging-par-headers-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 2. PAR file headers</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Header</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Application-SymbolicName</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Identifier for the application which, in combination with Application-Version, uniquely identifies an application</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Application-Name</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Human readable name of the application</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Application-Version</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Version of the application</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Application-Description</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Short description of the application</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The following code shows an example MANIFEST.MF in a PAR file:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="title">MANIFEST.MF</div> |
| <div class="content"> |
| <pre class="highlight"><code>Application-SymbolicName: com.example.shop |
| Application-Version: 1.0 |
| Application-Name: Online Shop |
| Application-Description: Example.com's Online Shopping Application</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>anchor:developing-applications-web-application-bundles</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_web_application_bundles">Web Application Bundles</h4> |
| <div class="paragraph"> |
| <p>Virgo for Apache Tomcat supports Web Application Bundles that are compliant with the OSGi Web Applications specification. |
| The defining property of a Bundle that makes it a Web Application Bundle is a manifest header, <code>Web-ContextPath</code>. |
| This defines the context path the web application will be registered under.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See <a href="#using-spring">Using Spring and Gemini Blueprint</a> for information on using Spring or Gemini Blueprint in a Web Application Bundle.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-plans"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_creating_plans">Creating Plans</h3> |
| <div class="paragraph"> |
| <p>Plans are similar to PARs in that they encapsulate the artifacts of an application as a single unit. |
| However plans are XML files that refer to their artifacts, whereas PARs are JAR files that physically contain their artifacts. |
| Plans, known as <strong>parent</strong> plans may refer to other plans, known as <strong>child</strong> plans.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Plans share several benefits with PARs:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>A plan has a (symbolic) name and a version.</p> |
| </li> |
| <li> |
| <p>A plan may be <strong>scoped</strong>, although this is optional. |
| See <a href="#developing-applications-plans-scoping">Plans and Scoping</a> for more on scoping.</p> |
| </li> |
| <li> |
| <p>A plan is visible to management interfaces.</p> |
| </li> |
| <li> |
| <p>A plan can be undeployed and redeployed as a unit.</p> |
| </li> |
| <li> |
| <p>A plan may be <strong>atomic</strong>, although this is optional.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Plans have the following additional benefits compared to PARs:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Virgo deploys the artifacts in the plan in the order in which they are listed in the XML file, which gives you |
| complete control over deployment order. |
| With a PAR, the order of deployment of the included artifacts is not guaranteed.</p> |
| </li> |
| <li> |
| <p>Since plans refer to their artifacts, it is easier to share content between plans as well as update individual |
| parts of a plan without having to physically repackage (re-JAR) it.</p> |
| </li> |
| <li> |
| <p>Plans may contain child plans, but PARs cannot contain other PARs.</p> |
| </li> |
| <li> |
| <p>You can make certain plans deploy faster by disabling the provisioning of bundles to satisfy missing dependencies, |
| but you cannot disable provisioning for PARs.</p> |
| </li> |
| <li> |
| <p>You can specify whether a plan is scoped or unscoped and atomic or non-atomic; PARs are always scoped and atomic.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The artifacts of a plan are usually stored in Virgo’s repository. This means, for example, that if you drop one of the plan’s artifacts in the <code>pickup</code> directory rather than adding it to the repository, the plan will fail to deploy because it will not find the artifact.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The artifacts of a plan may also be stored outside Virgo’s repository, somewhere else on the file system and referenced from the plan using URIs. |
| Such artifacts must be available on the file system when the plan is deployed and when Virgo restarts while the plan is deployed. |
| If you delete any of these artifacts, deployment of the plan may fail, either when it is initially deployed or when Virgo restarts.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-plans-create"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_creating_the_plan_xml_file">Creating the Plan XML File</h4> |
| <div class="paragraph"> |
| <p>Plans are XML files that have a <code>.plan</code> file extension, such as <code>multi-artifact.plan</code>. |
| The structure of the XML file is simple: |
| the root element is <code><plan></code> with attributes specifying the name of the plan, the version, atomicity, and scoping. |
| Then, for each artifact that makes up your application, |
| you add a <code><artifact></code> element, using its attributes to specify the type of artifact and its name and version. |
| The following is a simple example of a plan’s XML file:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> |
| <plan name="multi-artifact.plan" version="1.0.0" scoped="true" atomic="true" |
| xmlns="http://www.eclipse.org/virgo/schema/plan" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation=" |
| http://www.eclipse.org/virgo/schema/plan |
| http://www.eclipse.org/virgo/schema/plan/eclipse-virgo-plan.xsd"> |
| |
| <artifact type="configuration" name="app-properties" version="1.0.0"/> |
| <artifact type="bundle" name="com.springsource.exciting.app" version="[2.0.0, 3.1.0)"/> |
| |
| </plan></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In the preceding example, the name of the plan is <code>multi-artifact.plan</code> and its version is <code>1.0.0</code>. |
| The plan is both scoped and atomic. The plan contains two artifacts: one is a bundle called <code>com.springsource.exciting.app</code> and the other is a configuration file called <code>app-properties</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following table describes the attributes of the <code><plan></code> element.</p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 3. PAR file headers</caption> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 60%;"> |
| <col style="width: 20%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Attribute</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| <th class="tableblock halign-left valign-top">Required?</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>name</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the name of this plan. |
| Virgo uses the name as one component of the unique |
| identifier of this plan.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Yes.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>version</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the version of this plan. |
| You must use OSGi version specification syntax, |
| such as <code>2.1.0</code>. |
| Virgo uses the version as one component of |
| the unique identifier of this plan.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Yes.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>scoped</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies whether Virgo should install the |
| artifacts into plan-specific scope so that only the |
| application described by this plan has access to the artifacts. |
| If you disable scoping, then Virgo installs |
| the artifacts into the global scope, which means they |
| are then available for access by all other deployed artifacts. |
| Set the attribute to <code>true</code> to enable scoping or |
| <code>false</code> to disable it.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Yes.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>atomic</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies whether you want to tie together the lifecycle |
| of the artifacts in this plan. |
| Making a plan atomic means that if you start, stop, or |
| uninstall a single artifact in the plan, Virgo |
| escalates the operation to the whole plan. |
| Also Virgo prevents artifacts of an atomic plan |
| from being in inconsistent states. |
| For example, if one artifact should fail to start, |
| then Virgo stops all artifacts in the plan. |
| Set this attribute to <code>true</code> to enable atomicity or |
| <code>false</code> to disable it.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Yes.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>provisioning</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies whether Virgo installs bundles from |
| the repository to attempt to satisfy any missing |
| dependencies in the plan. |
| Missing dependencies prevent one or more bundles in |
| the plan from resolving. |
| For example, a bundle which imports a package cannot |
| resolve if the package is missing, that is, not |
| exported by another bundle. A value of |
| <code>auto</code> instructs Virgo to install bundles from the repository |
| to attempt to satisfy any missing dependencies in the plan. |
| This is known as <strong>auto-provisioning</strong>. |
| A value of <code>disabled</code> prevents Virgo from |
| installing bundles from the repository to attempt to |
| satisfy any missing dependencies in the plan. |
| This value can make the plan deploy faster, although if |
| there are missing dependencies, deployment will fail. |
| A value of <code>inherit</code>, which is the default if no value is specified, inherits the parent plan’s provisioning behaviour. |
| If the plan does not have a parent, it inherits Virgo’s |
| auto-provisioning behaviour.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">No. If not specified, defaults to <code>inherit</code>.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The following table describes the attributes of the <code><artifact></code> element. Note that you must either specify <code>type</code>, <code>name</code>, and (optionally) <code>version</code>, |
| in which case Virgo’s repository is searched for the artifact, or <code>uri</code> in which case the artifact is obtained directly from the file system. |
| If you specify <code>uri</code>, you must not specify <code>type</code>, <code>name</code>, or <code>version</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-plans-create-artifact-attributes"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 4. PAR file headers</caption> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 60%;"> |
| <col style="width: 20%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Attribute</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| <th class="tableblock halign-left valign-top">Required?</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the type of the artifact. Valid values are: |
| </p><p class="tableblock"><code>bundle</code>: Specifies an OSGi bundle. Use this artifact type for WAR files and Web application bundles. |
| <code>configuration</code>: Specifies that the artifact is a configuration file. Configuration files contain name/value pairs that set initial values for configuration properties of a bundle. |
| <code>plan</code>: Specifies that the artifact is a plan. |
| <code>par</code>: Specifies that the artifact is a PAR.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Yes, unless <code>uri</code> is specified in which case <code>type</code> must not be specified and is automatically determined from the artifact.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>name</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the name of the artifact. |
| See <a href="#artifact-names">Artifact Names</a> for guidelines for determining |
| the name of an artifact.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Yes, unless <code>uri</code> is specified in which case <code>name</code> must not be specified and is automatically determined from the artifact.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>version</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the range of versions of this artifact that |
| Virgo should look up in its repositories and |
| then install and deploy. |
| You must use OSGi version specification syntax, |
| such as <code>[1.0.0, 2.0.0)</code>. |
| Note that a single version number represents the range |
| from that version number upwards. |
| For example, <code>1.3</code> represents the range of versions |
| greater than or equal to <code>1.3</code>.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">No. If <code>uri</code> is specified, <code>version</code> must not be specified. |
| If neither <code>uri</code> nor <code>version</code> are specified, <code>version</code> defaults to <code>0</code>, which in OSGi means 0 to infinity, or any version.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>uri</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Specifies an optional, absolute URI string beginning |
| with <code>file:</code> that refers to the artifact on the file system. |
| Such an artifact must be available on the file system |
| when the plan is deployed and when Virgo restarts |
| while the plan is deployed. |
| If you delete such an artifact, deployment of the plan may fail, |
| either when it is initially deployed or when Virgo restarts. |
| This attribute is normally omitted so that the artifact |
| is searched for in Virgo’s repository.</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">No. If not specified, Virgo searches for the artifact in its repository.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a id="artifact-names"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_artifact_names">Artifact Names</h4> |
| <div class="paragraph"> |
| <p>When you create a plan, you use the <code>name</code> attribute of the <code><artifact></code> element to specify the name of all the plan’s dependencies. This section describes how to determine the name of an artifact, which is not always obvious.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Use the following guidelines to determine the name of an artifact:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Bundle</strong>: In this context, a <strong>bundle</strong> refers to a standard OSGi bundle as well as a Web Application Bundle and a WAR file. The name of a bundle is the value of the <code>Bundle-SymbolicName</code> header in the <code>META-INF/MANIFEST.MF</code> file of the <code>*.jar</code>. |
| If a WAR file has <code>Bundle-SymbolicName</code> header then it will be treated as a Web Application Bundle. The following <code>MANIFEST.MF</code> snippet shows a bundle with name <code>com.springsource.exciting.app</code>:</p> |
| </li> |
| </ul> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Bundle-SymbolicName: org.eclispe.virgo.exciting.app</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If the bundle does not contain a <code>META-INF/MANIFEST.MF</code> file or the <code>MANIFEST.MF</code> doesn’t contain a <code>Bundle-SymbolicName</code> header, then the name of the bundle is its filename minus the <code>.jar</code> or <code>.war</code> extension.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Configuration File</strong>: The name of a configuration or PID (Persistent Identity) is its filename minus the <code>.properties</code> extension. The PID can also be specified within the properties file with the |
| <strong>service.pid</strong> property.</p> |
| </li> |
| <li> |
| <p><strong>Plan</strong>: The name of a plan is the value of the required <code>name</code> attribute of the <code><plan></code> element in the plan’s XML file. In the following XML snippet, the plan name is <code>multi-artifact.plan</code>:</p> |
| </li> |
| </ul> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre><?xml version="1.0" encoding="UTF-8"?> |
| <plan name="multi-artifact.plan" version="1.0.0" scoped="true" atomic="true" |
| xmlns="http://www.eclipse.org/virgo/schema/plan"></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>PAR</strong>: The name of a PAR is the value of the <code>Application-SymbolicName</code> header in the <code>META-INF/MANIFEST.MF</code> file of the <code>*.par</code> file. The following <code>MANIFEST.MF</code> snippet shows a PAR with name <code>com.springsource.my.par</code>:</p> |
| </li> |
| </ul> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Application-SymbolicName: org.eclipse.virgo.my.par</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If the PAR does not contain a <code>META-INF/MANIFEST.MF</code> file, then the name of the PAR is its filename minus the <code>.par</code> extension.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="passing-properties"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_supplying_properties_to_artifacts">Supplying Properties to Artifacts</h4> |
| <div class="paragraph"> |
| <p>It is possible to pass properties to an artifact specified in a plan. An example of this can be seen in the Admin Console plan where the context path to be used in the Admin console is passed from the plan.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"><artifact type="bundle" name="org.eclipse.virgo.apps.admin.web" version="[3.0, 4.0)"> |
| <property name="header:Web-ContextPath" value="/admin" /> |
| </artifact></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The only supported property is <code>header</code> which will overwrite the given manifest header with the supplied value. This should be used with care!</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-plans-use"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_using_the_plan">Using the Plan</h4> |
| <div class="paragraph"> |
| <p>Because a plan is a list of artifacts, rather than a physical file that contains the artifacts, there are a few additional steps you must perform before you deploy it to Virgo.</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Copy the artifacts that make up the plan to the <code>usr</code> repository, which by default is the <code>$SERVER_HOME/repository/usr</code> directory, where <code>$SERVER_HOME</code> refers to the top-level installation directory of Virgo. Note that you might have configured the server differently; in which case, copy the artifacts to your custom repository directory.</p> |
| </li> |
| <li> |
| <p>Restart Virgo if the repository used is not a <strong>watched</strong> repository.</p> |
| </li> |
| <li> |
| <p>After the server has started, either use the Admin Console to deploy the plan, or manually deploy it by copying the plan’s XML file into the <code>$SERVER_HOME/pickup</code> directory.</p> |
| </li> |
| <li> |
| <p>This results in Virgo deploying the plan.</p> |
| </li> |
| <li> |
| <p>To undeploy the plan, use the Admin Console, or simply delete it from the <code>$SERVER_HOME/pickup</code> directory.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-plans-scoping"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_plans_and_scoping">Plans and Scoping</h4> |
| <div class="paragraph"> |
| <p>As described in previous sections, you can specify that a plan be <strong>scoped</strong>. This means that Virgo installs the artifacts that make up the plan into a plan-specific scope so that only the application described by the plan has access to the artifacts. If you disable scoping, then Virgo installs the artifacts into the global scope, which means they are available for access by all other deployed artifacts. This section describes scoping in a bit more detail. It also describes how you can change the default behavior of scoping, with respect to services, so that a service that is in a scope can be made globally available.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If a bundle in a given scope imports a package and a bundle in the same scope exports the package, then the import may only be satisfied by the bundle in the scope, and not by any bundles outside the scope, including the global scope. Similarly, package exports from bundles in a scope are not visible to bundles in the global scope.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If a bundle in a scope uses Spring DM (or the blueprint service) to obtain a service reference and a bundle in the same scope uses Spring DM (or the blueprint service) to publish a matching service, then the service reference may only bind to the service published in the scope (and not to any services outside the scope). Services published by bundles in a scope are not visible to bundles in the global scope.</p> |
| </div> |
| <div class="paragraph"> |
| <p>However, sometimes it is useful to make a service in a scope globally available to artifacts outside the scope. To do this, publish the service with the <code>org.eclipse.virgo.service.scope</code> service property set to <code>global</code>. Use the <code><service-properties></code> child element of <code><service></code>, as shown in the following example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"><service id="publishIntoGlobal" interface="java.lang.CharSequence"> |
| <service-properties> |
| <beans:entry key="org.eclipse.virgo.service.scope" value="global" /> |
| </service-properties> |
| <beans:bean class="java.lang.String"> |
| <beans:constructor-arg value="foo"/> |
| </beans:bean> |
| </service></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A scope forms a boundary for automatic propagation of load time weaving and bundle refresh. |
| Additionally, a synthetic context bundle is generated for each scope. This bundle imports all the packages exported by other bundles in the scope. |
| The class loader of the synthetic context bundle is used for thread context class loading. So, |
| for example, hibernate will be able to load classes of any of the exported |
| packages of the bundles in a scope using the thread context class loader.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To ensure predictable class loading behaviour and avoid other issues associated with <strong>split packages</strong> (packages whose classes |
| are split across more than one bundle), the synthetic context bundle has a restriction: |
| no package may be exported by more than one |
| bundle in the scope*. |
| If this restriction is broken, the scoped application will fail to deploy. |
| This restriction can cause problems for <a href="#scoping-and-substitutable-exports">substitutable exports</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-plans-scoping-webapps"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_web_applications_and_scoping">Web Applications and Scoping</h4> |
| <div class="paragraph"> |
| <p>A Web Application Bundle (WAB) or WAR has its bundle class loader set as the TCCL, even when the WAB or WAR belongs to |
| a PAR or scoped plan. |
| To enable the TCCL to load classes of other bundles in the same scope as a WAB or WAR, use a WAB which imports the necessary packages.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Also a WAB or WAR has its own per-application trace, independent of the per-application trace of any PAR or scoped plan to which the |
| WAB or WAR belongs.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-configuration-artifacts"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_creating_and_using_configuration_artifacts">Creating and Using Configuration Artifacts</h3> |
| <div class="paragraph"> |
| <p>Applications typically include some sort of configuration data |
| that might change depending on the environment in which the |
| application is deployed. For example, if an application connects to a |
| database server using JDBC, the configuration data would include the |
| JDBC URL of the database server, the JDBC drvier, and the username and |
| password that the application uses to connect to the database server. |
| This information often changes as the application is deployed to |
| different computers or the application moves from the testing phase to |
| the production phase.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Virgo provides a feature called |
| <strong>configuration artifacts</strong> |
| that makes it very easy for you to manage this configuration data. A |
| configuration artifact is simply a properties file that is made |
| available at runtime using the OSGi |
| <code>ConfigurationAdmin</code> |
| service. When you create this properties file, you set the values of |
| the properties for the specific environment in which you are going to |
| deploy your application, and then update the metadata of your Spring |
| application to use the properties file. You then deploy the |
| application and properties file together, typically as a |
| <a href="#developing-applications-plans">plan</a>. Virgo automatically creates a configuration artifact from |
| the properties file, and you can manage the lifecycle of this |
| configuration artifact in the same way you manage the lifecycle of |
| PARs, bundles, and plans, using the Admin |
| Console. Additionally, Virgo subscribes your |
| application for notification of any refresh of the configuration |
| artifact and the application can then adapt accordingly, which means |
| you can easily |
| <strong>change</strong> |
| the configuration of your application without redeploying it.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In sum, configuration artifacts, especially when combined with |
| plans, provide an excellent mechanism for managing external |
| configuration data for your applications.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following sections describe the format of the configuration |
| artifact, how to update the Spring application context file of your |
| application so that it knows about the configuration artifact, and |
| finally how to include it in a plan alongside your application.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As an example to illustrate the configuration artifact feature, assume |
| that you have a Spring bean called |
| <code>PropertiesController</code> |
| whose constructor requires that four property values be passed to it, |
| as shown in the following snippet of Java code:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-java" data-lang="java">@Controller |
| public class PropertiesController { |
| |
| private final String driverClassName; |
| private final String url; |
| private final String username; |
| private final String password; |
| |
| public PropertiesController(String driverClassName, String url, String username, String password) { |
| this.driverClassName = driverClassName; |
| this.url = url; |
| this.username = username; |
| this.password = password; |
| }</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In the preceding example, the <code>PropertiesController</code> constructor requires four property values: <code>driverClassName</code>, <code>url</code>, <code>username</code>, and <code>password</code>. Note that the example shows just one way that a class might require property values; your application may code it another way.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Additionally, assume that the following snippet of the associated Spring application context XML file shows how the <code>PropertiesController</code> bean is configured:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"><bean class="com.springsource.configuration.properties.PropertiesController"> |
| <constructor-arg value="${driverClassName}"/> |
| <constructor-arg value="${url}"/> |
| <constructor-arg value="${username}"/> |
| <constructor-arg value="${password}"/> |
| </bean></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The rest of this section describes how the bean can get these property values using a configuration artifact.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-configuration-artifacts-propfile"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_creating_the_properties_file">Creating the Properties File</h4> |
| <div class="paragraph"> |
| <p>To create a properties file that in turn will become a configuration artifact when deployed to Virgo from which a Spring bean, such as the <code>PropertiesController</code> bean, will get the actual property values, follow these guidelines:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Create a text file in which each property is listed as a name/value pair, one pair per line. Precede comments with a <code>#</code>. For example:</p> |
| </li> |
| </ul> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre># Properties for the com.springsource.configuration.properties sample |
| |
| driverClassName = org.w3.Driver |
| url = http://www.springsource.com |
| username = joe |
| password = secret</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The example shows four properties whose name correspond to the constructor arguments of the <code>PropertiesController</code> Spring bean.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Name the file anything you want, as long as it has a <code>.properties</code> extension, such as <code>app-properties.properties</code>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-configuration-artifacts-app"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_updating_your_application">Updating Your Application</h4> |
| <div class="paragraph"> |
| <p>To update your application so that it "knows" about the configuration artifact, you update the application’s Spring application context XML file, typically located in the <code>WEB-INF</code> or <code>META-INF/spring</code> directories (read <a href="#using-spring">Using Spring and Gemini Blueprint</a> |
| to understand which directory to use).</p> |
| </div> |
| <div class="paragraph"> |
| <p>You use the <code><context:property-placeholder></code> element to specify that you want to use the Virgo mechanism for substituting values into bean properties. The <code>properties-ref</code> attribute of this element points to a <code><osgi-compendium:cm-properties></code> element which you use to specify the configuration artifact that contains the property values. You set the value of the <code>persistent-id</code> attribute of this element equal to the name of the configuration artifact, which is the name of the properties file <strong>minus</strong> the <code>.properties</code> extension.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following sample Spring application context XMl file shows everything wired together; only relevant parts of the file are shown:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> |
| <beans xmlns="http://www.springframework.org/schema/beans" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xmlns:context="http://www.springframework.org/schema/context" |
| xmlns:osgi-compendium="http://www.springframework.org/schema/osgi-compendium" |
| xsi:schemaLocation="http://www.springframework.org/schema/osgi |
| http://www.springframework.org/schema/osgi/spring-osgi-1.2.xsd |
| http://www.springframework.org/schema/beans |
| http://www.springframework.org/schema/beans/spring-beans-2.5.xsd |
| http://www.springframework.org/schema/context |
| http://www.springframework.org/schema/context/spring-context-2.5.xsd |
| http://www.springframework.org/schema/osgi-compendium |
| http://www.springframework.org/schema/osgi-compendium/spring-osgi-compendium-1.2.xsd"> |
| |
| ... |
| |
| <bean class="com.springsource.configuration.properties.PropertiesController"> |
| <constructor-arg value="${driverClassName}"/> |
| <constructor-arg value="${url}"/> |
| <constructor-arg value="${username}"/> |
| <constructor-arg value="${password}"/> |
| </bean> |
| |
| <context:property-placeholder properties-ref="configAdminProperties"/> |
| |
| <osgi-compendium:cm-properties id="configAdminProperties" persistent-id="app-properties"/> |
| |
| ... |
| |
| </beans></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The preceding example shows how the id <code>configAdminProperites</code> wires the <code><context:property-placeholder></code> and <code><osgi-compendium:cm-properties></code> elements together. Based on the value of the <code>persistent-id</code> attribute, you must also deploy a properties file called <code>app-properties.properties</code> which Virgo installs as a configuration artifact.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-configuration-artifacts-plan"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_adding_the_configuration_artifact_to_a_plan">Adding the Configuration Artifact to a Plan</h4> |
| <div class="paragraph"> |
| <p>Although you can always deploy your application and associated configuration artifact using the <code>pickup</code> directory, we recommends that you group the two together in a plan, add the two artifacts to the repository, and then deploy the plan using the <code>pickup</code> directory. The following sample plan includes the two artifacts:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> |
| <plan name="multi-artifact.plan" version="1.0.0" |
| scoped="false" atomic="false" |
| xmlns="http://www.eclipse.org/virgo/schema/plan" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation=" |
| http://www.eclipse.org/virgo/schema/plan |
| http://www.eclipse.org/virgo/schema/plan/eclipse-virgo-plan.xsd"> |
| |
| <artifact type="configuration" name="app-properties" version="0"/> |
| <artifact type="bundle" name="org.eclipse.virgo.configuration.properties" version="1.0.0"/> |
| </plan></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>For additional information about plans, see <a href="#developing-applications-plans">Creating Plans</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="using-spring"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_using_spring_and_gemini_blueprint">Using Spring and Gemini Blueprint</h3> |
| <div class="paragraph"> |
| <p>Virgo supports the use of Spring framework and Gemini Blueprint by application bundles.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Spring (and Gemini Blueprint) application context XML files should generally be placed in a bundle’s <code>META-INF/spring</code> directory, but |
| for a web application, these files must be placed in the <code>WEB-INF</code> directory.</p> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Tip</div> |
| </td> |
| <td class="content"> |
| <div class="title">A common mistake</div> |
| <div class="paragraph"> |
| <p>Placing a web application’s Spring application context XML files in the <code>META-INF/spring</code> directory produces |
| unpredictable results since Spring DM will attempt to build an application context independently of, and asynchronously from, |
| the web application.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>To use Gemini Blueprint from a web application, the <code>contextClass</code> servlet parameter and the servlet context listener |
| should be configured (in <code>WEB-INF/web.xml</code>) like this:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"><context-param> |
| <param-name>contextClass</param-name> |
| <param-value>org.eclipse.virgo.web.dm.ServerOsgiBundleXmlWebApplicationContext</param-value> |
| </context-param> |
| |
| <listener> |
| <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class> |
| </listener></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Virgo has Gemini Blueprint built-in and thereby supports the OSGi Blueprint standard in addition to Spring DM.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For detailed information on Spring Framework and Blueprint, please see <a href="#prerequisites-references">Prerequisites</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-programmatic-access"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_programmatic_access_to_the_servlet_context">Programmatic Access to the Servlet Context</h3> |
| <div class="paragraph"> |
| <p>This section describes how to programmatically access the servlet context to obtain the WebApplicationContext or the BundleContext.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-programmatic-access-web"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_programmatic_access_to_web_features">Programmatic Access to Web Features</h4> |
| <div class="paragraph"> |
| <p><a id="developing-applications-programmatic-access-web-application-context"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_programmatic_access_to_the_webapplicationcontext">Programmatic Access to the WebApplicationContext</h4> |
| <div class="paragraph"> |
| <p>The Virgo for Apache Tomcat automatically creates a <code>WebApplicationContext</code> |
| for Web Application Bundles and WAR files. When used in conjunction with an |
| an auto-configured Spring MVC <code>DispatcherServlet</code>, |
| there is generally no need to access the <code>WebApplicationContext</code> |
| programmatically, since all components of the web application are configured |
| within the scope of the <code>WebApplicationContext</code> |
| itself. However, if you wish to access the <code>WebApplicationContext</code> |
| you can do so via the web application’s <code>ServletContext</code>. |
| Virgo stores the bundle’s |
| <code>WebApplicationContext</code> in the ServletContext under |
| the attribute name “BSN-ApplicationContext”, where |
| <code>BSN</code> is the <code>Bundle-SymbolicName</code> |
| of your WAR or Web Application Bundle.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Alternatively, since Virgo also stores the |
| <code>WebApplicationContext</code> under the attribute name |
| with the value of the <code>WebApplicationContext.ROOT_WEB_APPLICATION_CONTEXT_ATTRIBUTE</code> |
| constant, you may choose to use Spring MVC’s WebApplicationContextUtils' |
| <code>getWebApplicationContext(servletContext)</code> |
| or |
| <code>getRequiredWebApplicationContext(servletContext)</code> |
| methods to access the <code>WebApplicationContext</code> without providing |
| an explicit attribute name.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-programmatic-access-web-bundle-context"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_programmatic_access_to_the_bundlecontext">Programmatic Access to the BundleContext</h4> |
| <div class="paragraph"> |
| <p>As required by the OSGi Web Applications specification, you can access the |
| <code>BundleContext</code> of your WAR or Web Application Bundle via the web application’s |
| <code>ServletContext</code>. The bundle context is stored in the |
| <code>ServletContext</code> under the attribute name <code>osgi-bundlecontext</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-automatic-imports-web"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_web_application_manifest_processing">Web Application Manifest Processing</h3> |
| <div class="paragraph"> |
| <p>Virgo for Apache Tomcat generates automatic package imports (i.e., via the |
| <code>Import-Package</code> manifest header) for certain web applications. |
| This section lists which packages are automatically generated.</p> |
| </div> |
| <div class="paragraph"> |
| <p>VTS supports Web Application Bundles (WABs) as defined by the OSGi Web Applications Specification and WAR files. |
| A WAR will typically not contain any OSGi defined manifest headers. |
| A WAB is distinguished from a WAR by the presence of one or more of the following OSGi defined headers:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>Bundle-SymbolicName</code></p> |
| </li> |
| <li> |
| <p><code>Bundle-Version</code></p> |
| </li> |
| <li> |
| <p><code>Bundle-ManifestVersion</code></p> |
| </li> |
| <li> |
| <p><code>Import-Package</code></p> |
| </li> |
| <li> |
| <p><code>Web-ContextPath</code></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>As required by the OSGi Web Applications specification, the following defaults are applied to a WAR:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>Bundle-ManifestVersion</code> is set to <code>2</code></p> |
| </li> |
| <li> |
| <p><code>Bundle-SymbolicName</code> is generated from the path from which the bundle was installed</p> |
| </li> |
| <li> |
| <p><code>Bundle-ClassPath</code> is set to <code>WEB-INF/classes</code> followed by the JARs in |
| <code>WEB-INF/lib</code> in an unspecified order, followed by any transitive dependencies declared |
| by the JARs in <code>WEB-INF/lib</code></p> |
| </li> |
| <li> |
| <p><code>Import-Package</code> is extended in an implementation defined way, as described below</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following packages are automatically imported into WARs:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>javax.servlet;version="2.5"</code></p> |
| </li> |
| <li> |
| <p><code>javax.servlet.http;version="2.5"</code></p> |
| </li> |
| <li> |
| <p><code>javax.servlet.jsp;version="2.1"</code></p> |
| </li> |
| <li> |
| <p><code>javax.servlet.jsp.el;version="2.1"</code></p> |
| </li> |
| <li> |
| <p><code>javax.servlet.jsp.tagext;version="2.1"</code></p> |
| </li> |
| <li> |
| <p><code>javax.el;version="1.0"</code></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>In addition to the above-described imports, VTS will also |
| generate automatic imports for all of the packages that are exported by the system |
| bundle, unless an import for the package already exists in the WAR’s manifest, |
| or the WAR contains the package, i.e. within <code>WEB-INF/classes</code>, |
| or in a jar file in <code>WEB-INF/lib</code>. When an import is generated, it |
| is versioned such that it exactly matches the version or versions of the package that |
| are exported from the system bundle. For example, a package that’s exported only at |
| version <code>1.0.0</code> will generate an import with a version of |
| <code>[1.0.0,1.0.0]</code>, and a package that’s exported at version |
| <code>1.0.0</code> and version <code>2.0.0</code> will generate an import |
| with a version of <code>[1.0.0,2.0.0]</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Web Application Bundles are not subject to the above manifest processing. |
| This is a change of behaviour compared to Virgo Web Server 2.1.x. |
| See (see <a href="#known-issues-web-bundle-default-headers">Default Web |
| Application Bundle Headers</a>) if you need the old behaviour until you |
| have changed your WABs to match the new behaviour.</p> |
| </div> |
| <div class="paragraph"> |
| <p>VTS supports ROOT.war as a default web application. The <code>Web-ContextPath</code> |
| of the deployed ROOT.war is set to the default web context path - <code>/</code>.</p> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Tip</div> |
| </td> |
| <td class="content"> |
| <div class="title">System Bundle Package Exports</div> |
| <div class="paragraph"> |
| <p>For further details on which packages are exported by the |
| OSGi system bundle, consult the <filename>java-server.profile</filename> |
| file located in the <code>SERVER_HOME/configuration</code> directory.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-dependencies"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_working_with_dependencies">Working with Dependencies</h3> |
| <div class="paragraph"> |
| <p>Complex enterprise frameworks such a Spring and Hibernate are typically divided into many, many different |
| packages. Traditionally, if an OSGi bundle wished to make extensive use of such a framework its manifest would |
| have to import a huge number of different packages. This can be an error-prone and tedious process. Furthermore, |
| application developers are used to thinking in terms of their application using a framework, such as Spring, as a |
| whole, rather than a long list of all the different packages that comprise the framework.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following figure provides a simple illustration of the complexity of only using <code>Import-Package</code>:</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/import-package.png" alt="import package"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>Virgo reduces the need for long lists of imported packages by introducing two new manifest |
| headers; <code>Import-Bundle</code> and <code>Import-Library</code>. The following figure provides an |
| illustration of the simplification that these new headers offer:</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/import-bundle_import-library.png" alt="import bundle import library"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>As you can see, use of <code>Import-Bundle</code> and <code>Import-Library</code> can lead to a dramatic reduction |
| in the number of imports that you need to include in an application bundle’s manifest. Furthermore, <code>Import-Bundle</code> |
| and <code>Import-Library</code> are simply aliases for <code>Import-Package</code>; at deployment time <code>Import-Bundle</code> |
| and <code>Import-Library</code> header entries are automatically expanded into numerous <code>Import-Package</code> entries. This |
| means that you retain the exact same semantics of using <code>Import-Package</code>, without having to go through the labourious |
| process of doing so.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-importing-libraries"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_importing_libraries">Importing Libraries</h4> |
| <div class="paragraph"> |
| <p>A bundle in an application can declare a dependency on a library by using the |
| Eclipse Virgo specific <code>Import-Library</code> header. This header specifies a |
| comma-separated list of library symbolic names and version ranges that determine which libraries |
| are imported. By default a dependency on a library is mandatory but this can be |
| controlled through use of the resolution directive in exactly the same way as |
| it can with <code>Import-Package</code>.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">Import-Library: org.springframework.spring;version="[2.5.4, 3.0)", |
| org.aspectj;version="[1.6.0,1.6.0]";resolution:="optional"</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This example <code>Import-Library</code> header declares a mandatory dependency on the Spring |
| library at a version from 2.5.4 inclusive to 3.0 exclusive. It also declares an |
| optional dependency on the AspectJ library at exactly 1.6.0.</p> |
| </div> |
| <div class="paragraph"> |
| <p>anchor:developing-applications-importing-bundles</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_importing_bundles">Importing Bundles</h4> |
| <div class="paragraph"> |
| <p>A bundle in an application can declare a dependency on a bundle by using the |
| Eclipse Virgo specific <code>Import-Bundle</code> header. The header specifies a comma-separated |
| list of bundle symbolic names, version ranges, and scope declarmations that determine which bundles are imported and the scope of their dependency. By default a dependency |
| on a bundle is mandatory but this can be controlled through use of the resolution directive in exactly |
| the same way as it can with <code>Import-Package</code>.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">Import-Bundle: com.springsource.org.apache.commons.dbcp;version="[1.2.2.osgi, 1.2.2.osgi]"</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This example <code>Import-Bundle</code> header declares a mandatory dependency on the Apache Commons |
| DBCP bundle at exactly 1.2.2.osgi.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-importing-bundles-disadvantages"></a></p> |
| </div> |
| <div class="sect4"> |
| <h5 id="_disadvantages">Disadvantages</h5> |
| <div class="paragraph"> |
| <p>A disadvantage of using <code>Import-Bundle</code> or especially <code>Import-Library</code>, is that the application |
| bundle has a greater apparent fan-out than it strictly needs. An Alternative is to use a tool such as bnd or Bundlor |
| to generate the package imports of the bundle.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-scoping-libraries-bundles"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_scoping_bundles_in_an_application">Scoping Bundles in an Application</h4> |
| <div class="paragraph"> |
| <p>When working with a scoped application, such as a PAR file or a plan, you might run into a situation where one of the bundles in the application (call it <code>bundleA</code>) depends on another bundle (<code>bundleB</code>) that performs a runtime task (such as class generation) that a third bundle (<code>bundleC</code>) might need to know about, although <code>bundleC</code> does not explicitly depend on <code>bundleB</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, Hibernate uses CGLIB (code generation library) at runtime to generate proxies for persistent classes. Assume that a domain bundle in your application uses Hibernate for its persistent objects, and thus its <code>Import-Bundle</code> manifest header includes the Hibernate bundle. Further assume that a separate Web bundle uses reflection in its data-binding code, and thus needs to reflect on the persistent classes generated by Hibernate at runtime. The Web bundle now has an indirect dependency on the Hibernate bundle because of these dynamically generated classes, although the Web bundle does not typically care about the details of how these classes are persisted. One way to solve this dependency problem is to explicitly add the Hibernate bundle to the <code>Import-Bundle</code> header of the Web bundle; however, this type of explicit-specified dependency breaks the modularity of the application and is not a programming best practice.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A better way to solve this problem is to specify that Virgo itself dynamically import |
| the bundle (Hibernate in the example above) to all bundles in the application at runtime. |
| You do this by adding the <code>import-scope:=application</code> directive to the <code>Import-Bundle</code> header |
| of the bundle that has the direct dependency (the domain bundle in our example). At runtime, although the Web bundle |
| does not explicitly import the Hibernate bundle, Virgo implicitly imports it and thus its classes are available |
| to the Web bundle. This mechanism allows you to declare the dependencies you need to make your application run, |
| without having to make changes to your application that might limit its flexibility.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following example shows how to use the <code>import-scope</code> directive with the <code>Import-Bundle</code> header:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">Import-Bundle: com.springsource.org.hibernate;version="[3.2.6.ga,3.2.6.ga]";import-scope:=application</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>You can also set the <code>import-scope</code> directive to the (default) value <code>bundle</code>; in this case, the scope of the bundle is just the bundle itself and thus Virgo does not perform any implicit importing into other bundles of the application.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that use of the <code>import-scope:=application</code> directive of the <code>Import-Bundle</code> header only makes sense when the bundle is part of a scoped application (PAR or plan); if the bundle is not part of a scoped application, then this directive has no effect.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Finally, because <code>import-scope:=application</code> implicitly adds a bundle import to each bundle of the PAR or plan, the impact of subsequently refreshing the imported bundle is, in general, broader than it would have been if you had not used <code>import-scope:=application</code>. This may well affect the performance of refresh.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-defining-libraries"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_defining_libraries">Defining Libraries</h4> |
| <div class="paragraph"> |
| <p>Libraries are defined in a simple text file, typically with a <code>.libd</code> suffix. This file identifies the |
| library and lists all of its constituent bundles. For example, the following is the library definition for |
| Spring 2.5.4:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">Library-SymbolicName: org.springframework.spring |
| Library-Version: 2.5.4 |
| Library-Name: Spring Framework |
| Import-Bundle: org.springframework.core;version="[2.5.4,2.5.5)", |
| org.springframework.beans;version="[2.5.4,2.5.5)", |
| org.springframework.context;version="[2.5.4,2.5.5)", |
| org.springframework.aop;version="[2.5.4,2.5.5)", |
| org.springframework.web;version="[2.5.4,2.5.5)", |
| org.springframework.web.servlet;version="[2.5.4,2.5.5)", |
| org.springframework.jdbc;version="[2.5.4,2.5.5)", |
| org.springframework.orm;version="[2.5.4,2.5.5)", |
| org.springframework.transaction;version="[2.5.4,2.5.5)", |
| org.springframework.context.support;version="[2.5.4,2.5.5)", |
| org.springframework.aspects;version="[2.5.4,2.5.5)", |
| com.springsource.org.aopalliance;version="1.0"</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following table lists all of the headers that may be used in a library definition:</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-defining-libraries-library-headers-table"></a></p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 5. Library definition headers</caption> |
| <colgroup> |
| <col style="width: 28%;"> |
| <col style="width: 71%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Header</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Library-SymbolicName</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Identifier for the library</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Library-Version</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Version number for the library</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Import-Bundle</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A comma separated list of bundle symbolic names. |
| Each entry may optionally specify a version (using the <code>version=</code> directive) |
| and the scope of the import (using the <code>import-scope</code> directive).</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Library-Name</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Optional. The human-readable name of the library</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Library-Description</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Optional. A human-readable description of the library</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p><a id="developing-applications-installing-dependencies"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_installing_dependencies">Installing Dependencies</h4> |
| <div class="paragraph"> |
| <p>Rather than encouraging the packaging of all an application’s dependencies within the application itself, Virgo |
| uses a local provisioning repository of bundles and libraries upon which an application can depend. When the Virgo |
| encounters an application with a particular dependency, it will automatically provide, from its provisioning repository, |
| the appropriate bundle or library.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Making a dependency available for provisioning is simply a matter of copying it to the appropriate location in the |
| Virgo’s local provisioning repository. By default this is |
| <code>SERVER_HOME/repository/usr</code>. A more detailed discussion of the provisioning |
| repository can be found in the <a href="http://www.eclipse.org/virgo/documentation/virgo-documentation-3.7.1.RELEASE/docs/virgo-user-guide/html/index.html">User Guide</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-application-trace"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_application_trace">Application Trace</h3> |
| <div class="paragraph"> |
| <p>As described in the <a href="http://www.eclipse.org/virgo/documentation/virgo-documentation-3.7.1.RELEASE/docs/virgo-user-guide/html/index.html">User Guide</a> Virgo provides support for |
| per-application trace for PARs, scoped Plans and WABs. Virgo provides SLF4J with Logback logging for Event Logging and Tracing. |
| Application trace is configured in the <code>serviceability.xml</code> file. |
| See the <a href="http://www.eclipse.org/virgo/documentation/virgo-documentation-3.7.1.RELEASE/docs/virgo-user-guide/html/index.html">User Guide</a> for more details.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="developing-applications-versioning"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_application_versioning">Application Versioning</h3> |
| <div class="paragraph"> |
| <p>In much the same way that individual OSGi bundles can be versioned, Virgo allows applications to be versioned. How exactly you do this depends on how you have packaged the application:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If you package your application using a PAR, you version the application by using the <code>Application-Version</code> header in the <code>MANIFEST.MF</code> file of the PAR file.</p> |
| </li> |
| <li> |
| <p>If you use a plan to describe the artifacts that make up your application, you version it by using the <code>version</code> attribute of the <code><plan></code> root element of the plan’s XML file.</p> |
| </li> |
| <li> |
| <p>If your application consists of a single bundle, you version it in the standard OSGi way: by using the <code>Bundle-Version</code> header of the <code>MANIFEST.MF</code> file of the bundle.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Virgo uses an application’s version to prevent clashes when multiple versions of the same application are deployed at |
| the same time. For example, the application trace support described in <a href="#developing-applications-application-trace">Application Trace</a>, |
| includes the application’s name and version in the file path. This ensures that each version of the same application has its |
| own trace or logging file.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="migrating-to-osgi"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_migrating_to_osgi">Migrating to OSGi</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Taking on a new technology such as OSGi may seem a bit daunting at first, |
| but a proven set of migration steps can help ease the journey. Teams |
| wishing to migrate existing applications to run on the Virgo for Apache Tomcat |
| will find that their applications typically fall into one of the following |
| categories.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Web Application</strong>: for web applications, |
| this chapter provides an overview of the steps required to migrate |
| from a Standard WAR to a Shared Services WAR. Furthermore, the following |
| chapter provides a detailed case study involving the migration |
| of the Spring 3.0 Form Tags show case application.</p> |
| </li> |
| <li> |
| <p><strong>Anything else</strong>: for any other type |
| of application, you will typically either deploy your application |
| as multiple individual bundles, as a single PAR file, or as a plan, |
| which is the recommended approach for deploying applications on |
| the Virgo for Apache Tomcat. See <a href="#migrating-to-osgi-par-plan">Migrating to a Plan or a PAR</a> for details.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a id="migrating-to-osgi-web"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_migrating_web_applications">Migrating Web Applications</h3> |
| <div class="paragraph"> |
| <p>Many applications may start with the standard WAR format for web applications and |
| gradually migrate to a more OSGi-oriented architecture. Since the Virgo for Apache Tomcat |
| offers several benefits to all supported deployment formats, it provides a smooth |
| migration path. Of course, depending on your application’s complexity and your |
| experience with OSGi, you may choose to start immediately with an OSGi-based |
| architecture.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="migrating-to-osgi-web-standard-war"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_standard_war_2">Standard WAR</h4> |
| <div class="paragraph"> |
| <p>If you are not yet familiar with OSGi or simply want to deploy an existing web application on the Virgo for Apache Tomcat, |
| you can deploy a standard WAR and leverage the VTS with a minimal learning curve. In fact reading the |
| <a href="../../virgo-user-guide/html/index.html">User Guide</a> |
| is pretty much all that you need to do to get started. Furthermore, you will gain |
| familiarity with the Virgo for Apache Tomcat, while preparing to take advantage of the other formats.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="migrating-to-osgi-web-shared-libraries-war"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_shared_libraries_war_2">Shared Libraries WAR</h4> |
| <div class="paragraph"> |
| <p>The <strong>Shared Libraries WAR</strong> |
| format is the first step to reaping the benefits of OSGi. In this phase, you dip your toes into OSGi-based dependency |
| management by removing JAR files from the WAR and declaring dependencies on corresponding OSGi bundles.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="migrating-to-osgi-web-shared-services-war"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_shared_services_war_2">Shared Services WAR</h4> |
| <div class="paragraph"> |
| <p>In this phase, you take the next step toward a fully OSGi-based architecture by separating your web artifacts |
| (e.g., Servlets, Controllers, etc.) from the services they depend on.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="migrating-to-osgi-web-summary"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_web_migration_summary">Web Migration Summary</h4> |
| <div class="paragraph"> |
| <p>The following diagram graphically depicts the migration path from a Standard WAR to a Shared Services WAR. |
| As you can see, the libraries (<strong>libs</strong>) move from within the deployment artifact |
| to the Bundle Repository. |
| Similarly, the services move from within the WAR to external bundles and are accessed via the |
| OSGi Service Registry. In addition, the overall footprint of the deployment artifact decreases |
| as you move towards a Shared Services WAR. |
| <span class="image"><img src="assets/images/migration-path-war-to-shsrv.png" alt="migration path war to shsrv"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="migrating-to-osgi-par-plan"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_migrating_to_a_plan_or_a_par">Migrating to a Plan or a PAR</h3> |
| <div class="paragraph"> |
| <p>The first steps to migrating an existing application to a plan or a PAR are the same: deciding on the bundles that make up the application and ensuring that their <code>Import-Package</code>, <code>Import-Library</code>, and <code>Import-Bundle</code> manifest headers are correct. Once you have the list of bundles that make up your application, you then decide whether you want to JAR them all into a single application file (PAR) or create a plan that simply lists the bundles by reference. Creating a plan is the recommend way to create an application, although PARs also have benefits that might suit your needs better, as described in <a href="#migrating-to-osgi-parplan-decide">Plan or PAR?</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="migrating-to-osgi-parplan-bundles"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_creating_the_application_bundles">Creating the Application Bundles</h4> |
| <div class="paragraph"> |
| <p>When migrating an existing application to the PAR packaging and deployment format or a plan, |
| you consider modularity as the prime objective. Following the ideas discussed in |
| <a href="#architecture-forming-bundles">A Guide to Forming Bundles</a>, you refactor the application into multiple bundles. |
| You may start conservatively with a small number of bundles and then further refactor those bundles.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the original code is crafted following good software practices such as separation of concerns and use of |
| well-defined interfaces, migration may involve modifying only configuration and packaging. In other words, |
| your Java sources will remain unchanged. Even configuration is likely to change only slightly.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, the following diagram depicts a typical web application that has been refactored and |
| packaged as a PAR. The blue elements within the <strong>Application</strong> box constitute |
| the bundles of the application. Each of these bundles imports types from other bundles within |
| the PAR using <code>Import-Package</code>. The green elements in the left column represent |
| <strong>libraries</strong> installed on the VTS. The PAR’s bundles reference these |
| libraries using <code>Import-Library</code>. The purple element in the left column |
| represents a bundle within the VTS’s bundle repository which is imported by the DAO |
| bundle using <code>Import-Bundle</code>. In contrast to a traditional, monolithic |
| WAR deployment, the PAR format provides both a logical and physical application boundary |
| and simultaneously allows the application to benefit from both the OSGi container and the Virgo for Apache Tomcat. |
| <span class="image"><img src="assets/images/migrating-to-osgi-par-structure.png" alt="migrating to osgi par structure"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="migrating-to-osgi-parplan-decide"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_plan_or_par">Plan or PAR?</h4> |
| <div class="paragraph"> |
| <p>Once you have refactored your existing application into separate OSGi bundles, you then must decide whether to package the bundles into a single PAR file or create a plan that lists the bundles by reference. As described in more detail in preceding sections of this guides, PARs and plans have similar benefits, such as:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Scoping</p> |
| </li> |
| <li> |
| <p>Atomicity, or the ability to deploy and control the bundles as a single unit</p> |
| </li> |
| <li> |
| <p>Versioning</p> |
| </li> |
| <li> |
| <p>Improved serviceability</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Plans, the method most recommended by us to create your application, has the following added benefits:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Guaranteed order of deployment, based on the order in which they are listed in the plan’s XML file</p> |
| </li> |
| <li> |
| <p>Ease of sharing content between plans and updating individual plans without having to physically repackage, due to the artifacts being listed by reference.</p> |
| </li> |
| <li> |
| <p>Ability to disable scoping and atomicity, if desired.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The main benefit of PARS is that, because they physically contain all the required artifacts, you know exactly what bundles are deployed when you deploy the PAR file, in contrast to plans that allow content to be substituted or lost.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For details about creating plans and PARs, see <a href="#developing-applications-plans">Creating Plans</a> and <a href="#developing-applications-packaging">Creating PARs and Web Applications</a>, respectively.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="formtags-case-study"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_case_study_migrating_the_form_tags_sample_application">Case Study: Migrating the Form Tags Sample Application</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Migrating Form Tags</p> |
| </div> |
| <div class="paragraph"> |
| <p>In this chapter we will walk through the steps needed to migrate the |
| Form Tags sample application from a standard Java EE WAR to a fully |
| OSGi compliant <strong>Shared Services WAR</strong> within a PAR. |
| The migration involves four packaging and deployment formats:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p><a href="#formtags-case-study-war">Standard WAR</a></p> |
| </li> |
| <li> |
| <p><a href="#formtags-case-study-war-shared-libs">Shared Libraries WAR</a></p> |
| </li> |
| <li> |
| <p><a href="#formtags-case-study-war-shared-services">Shared Services WAR</a></p> |
| </li> |
| <li> |
| <p><a href="#formtags-case-study-par">PAR with a shared services WAR</a></p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>Each of these migration steps will produce a web application |
| that can be deployed and run on the VTS.</p> |
| </div> |
| <div class="paragraph"> |
| <p>After summarising the process, an example <code>plan</code> |
| is shown which is another way of packaging and deploying the application.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following image displays the directory structure you should have |
| after installing the Form Tags sample. Note however that the release |
| tag will typically resemble <code>3.0.0.RELEASE</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/formtags-case-study-sample-layout.png" alt="formtags case study sample layout"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>dist</code> directory contains the distributables, |
| and the <code>projects</code> directory contains the source code and build scripts.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For simplicity, this chapter will focus on the distributables—which |
| are built using Virgo-Build rather than on configuring a project in an IDE.</p> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Tip</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Pre-packaged distributables are made available in the <code>dist</code> directory; |
| however, if you would like to modify the samples or build |
| them from scratch, you may do so using Virgo-Build. Take a look at |
| the <code>README.TXT</code> file in each of the folders under the <code>projects</code> |
| directory in the Form Tags sample for instructions.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a id="formtags-case-study-introduction"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_overview_of_the_form_tags_sample_application">Overview of the Form Tags Sample Application</h3> |
| <div class="paragraph"> |
| <p>The sample that we will be using is the Form Tags show case |
| sample |
| which was provided with Spring 2.0. The Form Tags application |
| has |
| been removed from the official Spring 2.5.x distributions; |
| however, |
| since it is relatively simple but still contains enough |
| ingredients |
| to demonstrate the various considerations required during |
| a migration, |
| we have chosen to use it for these examples.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The purpose of the Form Tags show case sample was to demonstrate how |
| the Spring specific |
| <code>form:</code> |
| tags, released |
| in Spring 2.0, make view development with JSPs and tag |
| libraries easier. |
| The Form Tags application consists of a single |
| <code>UserService</code> |
| which returns a list |
| of |
| <code>Users</code> |
| . Furthermore, the application demonstrates how to list, view, |
| and |
| edit |
| <code>Users</code> |
| in a simple Spring MVC based web application using JSP |
| and JSTL.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="formtags-case-study-war"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_form_tags_war">Form Tags WAR</h3> |
| <div class="paragraph"> |
| <p>We begin with a standard WAR deployment.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>The VTS supports the standard Java EE WAR |
| packaging |
| and deployment format as a first-class citizen, and there |
| are many |
| benefits to deploying a standard WAR file on the |
| VTS including, |
| but not limited to: tooling |
| support, runtime error diagnostics, FFDC |
| (first failure data |
| capture), etc. |
| In addition, support for standard WAR deployment |
| provides an easy on-ramp |
| for trying out the |
| VTS with existing web applications.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The following screen shot displays the directory structure of the |
| Form Tags application using the standard WAR format. As you can see, |
| there is no deviation from the standard structure and layout, and as |
| you would expect, all of the web application’s third-party |
| dependencies |
| (for example: Spring, Commons Logging) are packaged as |
| JARs in |
| <code>WEB-INF/lib</code> |
| .</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/formtags-case-study-exploded-war.png" alt="formtags case study exploded war"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>To deploy this application, simply copy |
| <code>dist/formtags-war-3.0.0.*.war</code> |
| to |
| the |
| <code>SERVER_HOME/pickup</code> |
| directory for hot deployment.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You should then see the VTS produce |
| console output similar to the following:</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>The console output has been reformatted to fit this document.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">[2009-07-01 14:54:45.135] fs-watcher |
| <SPDE0048I> Processing 'CREATED' event for file 'formtags-war-3.0.0.RELEASE.war'. |
| [2009-07-01 14:54:45.797] fs-watcher |
| <SPDE0010I> Deployment of 'formtags-war-3.0.0.RELEASE.war' version '0' completed. |
| [2009-07-01 14:54:45.797] Thread-20 |
| <SPWE0000I> Starting web bundle '/formtags-war-3.0.0.RELEASE'. |
| [2009-07-01 14:54:46.380] Thread-20 |
| <SPWE0001I> Started web bundle '/formtags-war-3.0.0.RELEASE'.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Navigate to |
| <code><a href="http://localhost:8080/" class="bare">http://localhost:8080/</a></code> |
| plus the web application context path, |
| which in the above case is |
| <code>formtags-war-3.0.0.RELEASE</code> |
| . Thus navigating to |
| <code><a href="http://localhost:8080/formtags-war-3.0.0.RELEASE" class="bare">http://localhost:8080/formtags-war-3.0.0.RELEASE</a></code> |
| should render the sample application’s welcome page, as |
| displayed in the screen |
| shot below.</p> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Tip</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>For WARs, the default web context path is the name of the WAR file |
| without the |
| <code>.war</code> |
| extension. You can optionally |
| specify a context path using the |
| <code>Web-ContextPath</code> |
| bundle |
| manifest header, which will be described in further detail |
| later.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/formtags-case-study-war-webpage.png" alt="formtags case study war webpage"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="formtags-case-study-war-shared-libs"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_form_tags_shared_libraries_war">Form Tags Shared Libraries WAR</h3> |
| <div class="paragraph"> |
| <p>As mentioned above, a standard WAR file typically packages of all its |
| required |
| dependencies in |
| <code>WEB-INF/lib</code> |
| . The servlet container will |
| then add all of the JARs in |
| <code>WEB-INF/lib</code> |
| to the application’s |
| classpath.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The first step of the migration towards benefiting from an OSGi |
| container is to retrieve the dependencies from the |
| VTS’s bundle |
| repository at runtime. This |
| can significantly reduce the time it takes to build |
| and deploy the |
| application. It also enables the enforcement of policies |
| regarding the |
| use of third-party libraries.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The way in which dependencies are declared in an OSGi environment is |
| via manifest headers in a bundle’s |
| <code>/META-INF/MANIFEST.MF</code> |
| . |
| As mentioned in <a href="#developing-applications">Developing Applications</a>, there are |
| three ways of expressing dependencies: |
| <code>Import-Package</code>, |
| <code>Import-Bundle</code> and |
| <code>Import-Library</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Form Tags application uses JSTL standard tag libraries. |
| Thus, you |
| need to choose a JSTL provider, for example the |
| Apache implementation |
| which comes with the VTS. To use the |
| Apache |
| implementation of JSTL, you need to express your dependency |
| as |
| outlined in the following manifest listing. |
| Because it is a single |
| bundle, |
| <code>Import-Bundle</code> |
| is |
| the simplest and therefore preferred manifest header to use.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Form Tags application requires commons-logging and Spring. |
| It |
| would be very painful to have to list all the Spring packages one by |
| one. |
| Equally, considering the number of bundles that make up the |
| Spring framework, it would be verbose to list each bundle. Therefore |
| <code>Import-Library</code> |
| is the preferred approach |
| for expressing the dependency on the Spring |
| framework.</p> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Tip</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>How do you determine the name of a library definition provided |
| by the Virgo for Apache Tomcat? Use the <a href="http://www.eclipse.org/ebr">EBR</a>.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Examine the |
| <code>/META-INF/MANIFEST.MF</code> |
| in |
| <code>/dist/formtags-shared-libs-*.war</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">Manifest-Version: 1.0 |
| Ant-Version: Apache Ant 1.7.0 |
| Created-By: 1.5.0_13-119 (Apple Inc.) |
| Bundle-ManifestVersion: 2 |
| Bundle-SymbolicName: org.springframework.showcase.formtags-shared-libs |
| Import-Library: org.springframework.spring;version="[3.0.0,4.0.0)" |
| Import-Bundle: com.springsource.org.apache.taglibs.standard;version="1 |
| .1.2"</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>You can see the |
| <code>Import-Library</code> |
| and |
| <code>Import-Bundle</code> |
| directives that instruct the VTS to add the |
| appropriate package imports to the bundle |
| classpath used by this WAR file.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Deploying the shared libraries WAR onto the |
| VTS should result |
| in console output similar to |
| the following:</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>The console output has been reformatted to fit this document.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">[2009-07-01 15:00:14.953] fs-watcher |
| <SPDE0048I> Processing 'CREATED' event for file 'formtags-shared-libs-3.0.0.RELEASE.war'. |
| [2009-07-01 15:00:15.363] fs-watcher |
| <SPDE0010I> Deployment of 'org.springframework.showcase.formtags_shared_libs' version '2' completed. |
| [2009-07-01 15:00:15.364] Thread-20 |
| <SPWE0000I> Starting web bundle '/formtags-shared-libs-3.0.0.RELEASE'. |
| [2009-07-01 15:00:15.816] Thread-20 |
| <SPWE0001I> Started web bundle '/formtags-shared-libs-3.0.0.RELEASE'.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Navigating to |
| <code><a href="http://localhost:8080/formtags-shared-libs-BUILDTAG" class="bare">http://localhost:8080/formtags-shared-libs-BUILDTAG</a> |
| ` |
| should render the welcome page. Note that for the pre-packaged |
| distributable, |
| the |
| `BUILDTAG</code> |
| should be similar to |
| <code>3.0.0.RELEASE</code> |
| ; |
| whereas, for a local build the |
| <code>-BUILDTAG</code> |
| may be completely |
| omitted. Please consult the console output, |
| web-based admin console, or log |
| to determine the exact context path |
| under which the web application has been deployed.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="formtags-case-study-war-shared-services"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_form_tags_shared_services_war">Form Tags Shared Services WAR</h3> |
| <div class="paragraph"> |
| <p>The next step in the migration is to deploy the services as a |
| separate |
| OSGi bundle which the WAR then references. |
| The Form Tags |
| sample has a single service |
| <code>UserManager</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This scenario has two separate deployables, the |
| <code>service</code> |
| bundle and the WAR file. |
| The following image shows the two separate |
| source trees:</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/formtags-case-study-shared-services-eclipse.png" alt="formtags case study shared services eclipse"></span></p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Note that the WAR does not contain the |
| <code>.domain</code> |
| or |
| <code>.service</code> |
| packages as these will be imported from the separate service bundle.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a id="formtags-case-study-war-shared-services-service"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_the_service_bundle">The Service Bundle</h4> |
| <div class="paragraph"> |
| <p>The responsibility of the first bundle ( |
| <code>formtags-shared-services-service</code> |
| ) |
| is to provide the API of the formtags service. This includes both |
| the |
| domain and the service API. In the same way that imports are |
| defined |
| in the |
| <code>/META-INF/MANIFEST.MF</code> |
| , so are exports. |
| The following is the |
| <code>/META-INF/MANIFEST.MF</code> |
| listing from the service bundle.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">Manifest-Version: 1.0 |
| Ant-Version: Apache Ant 1.7.0 |
| Created-By: 1.5.0_13-119 (Apple Inc.) |
| Bundle-ManifestVersion: 2 |
| Bundle-Name: FormTags Service (and implementation) |
| Bundle-SymbolicName: org.springframework.showcase.formtags.service-shared-services |
| Export-Package: org.springframework.showcase.formtags.service,org.spri |
| ngframework.showcase.formtags.domain |
| Import-Library: org.springframework.spring;version="[3.0.0,4.0.0)"</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The symbolic name of this bundle is |
| <code>org.springframework.showcase.formtags.service-shared-services</code>. |
| Note that the name of the bundle typically describes the package that the bundle primarily exports. |
| If you take a look at the <code>repository/bundles/ext</code> in the VTS |
| directory, you’ll see that |
| names are almost always indicative of the contents of the bundle. |
| For this example, however, we have also appended |
| “-shared-services” |
| in order to avoid possible clashes with other bundle symbolic |
| names. |
| You will see later that the PAR also contains a service |
| bundle.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>In OSGi, the combination of |
| <code>Bundle-SymbolicName</code> |
| and |
| <code>Bundle-Version</code> |
| is used to uniquely identify |
| a bundle within the OSGi container. |
| Furthermore, when you deploy |
| a bundle to the Virgo for Apache Tomcat, |
| for example via the |
| <code>pickup</code> |
| directory, a bundle’s filename is also used to uniquely |
| identify it for |
| the purpose of supporting |
| <strong>hot deployment</strong> |
| via |
| the file system.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>As well as exporting types (i.e. the domain classes and service |
| API), the service bundle also publishes an implementation of the |
| <code>UserManager</code> |
| . The actual implementation is |
| <code>StubUserManager</code> |
| ; however, that should remain an |
| implementation detail of this |
| bundle.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The fact that this bundle publishes a service is not captured in |
| the |
| <code>/META-INF/MANIFEST.MF</code> |
| , as it is a Gemini Blueprint concept. |
| The following image is of |
| <code>src/main/resources/spring</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/formtags-case-study-shared-services-service-resources.png" alt="formtags case study shared services service resources"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>As you can see there are two Spring configuration files: |
| <code>module-context.xml</code> |
| and |
| <code>osgi-context.xml</code>.</p> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Tip</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>These names are abitrary; however, they follow an informal |
| convention: |
| <code>module-context.xml</code> |
| typically bootstraps the Spring context |
| (usually delegating to |
| smaller fine grained context files inside another directory), |
| whilst |
| <code>osgi-context.xml</code> |
| contains all the OSGi service exports and references.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The following is a listing of |
| <code>module-context.xml</code> |
| .</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> |
| |
| <beans xmlns="http://www.springframework.org/schema/beans" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation=" |
| http://www.springframework.org/schema/beans |
| http://www.springframework.org/schema/beans/spring-beans-2.5.xsd"> |
| |
| <bean id="userManager" |
| class="org.springframework.showcase.formtags.service.internal.StubUserManager"/> |
| |
| </beans></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>As you can see, this simply defines a bean called |
| <code>userManager</code> |
| . |
| The following is a listing of |
| <code>osgi-context.xml</code>.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> |
| <beans:beans |
| xmlns="http://www.springframework.org/schema/osgi" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xmlns:beans="http://www.springframework.org/schema/beans" |
| xsi:schemaLocation="http://www.springframework.org/schema/osgi |
| http://www.springframework.org/schema/osgi/spring-osgi.xsd |
| http://www.springframework.org/schema/beans |
| http://www.springframework.org/schema/beans/spring-beans.xsd"> |
| |
| <service ref="userManager" |
| interface="org.springframework.showcase.formtags.service.UserManager"/> |
| |
| </beans:beans></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This single bean definition exports the |
| <code>userManager</code> |
| defined in |
| <code>module-context.xml</code> |
| to the |
| OSGi service registry and makes it available under the public |
| `org.springframework.showcase.formtags.service.UserManager |
| ` |
| API.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The service bundle should now be ready to deploy on the |
| VTS. |
| So copy |
| <code>/dist/formtags-shared-services-services*</code> |
| to the |
| <code>SERVER_HOME/pickup</code> |
| directory. |
| Output similar to the following should appear in the |
| VTS’s console:</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>The console output has been reformatted to fit this document.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">[2009-07-01 15:05:03.511] fs-watcher |
| <SPDE0048I> Processing 'CREATED' event for file 'formtags-shared-services-service-2.0.0.RELEASE.jar'. |
| [2009-07-01 15:05:03.688] fs-watcher |
| <SPDE0010I> Deployment of 'org.springframework.showcase.formtags.service_shared_services' version '2.0.0.RELEASE' completed.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><a id="formtags-case-study-war-shared-services-war"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_accessing_the_service_and_types_from_the_war">Accessing the Service and Types from the WAR</h4> |
| <div class="paragraph"> |
| <p>The WAR file now needs to access the types and service exported |
| by |
| the service bundle. The following listing is the WAR’s |
| <code>/META-INF/MANIFEST.MF</code> |
| which imports the types |
| exported by the service bundle. The |
| <code>Import-Bundle</code> |
| statement has also been extended to import |
| <code>org.springframework.osgi.core</code> |
| , |
| which is necessary in order to load an OSGi-enabled |
| <code>WebApplicationContext</code> |
| .</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">Manifest-Version: 1.0 |
| Ant-Version: Apache Ant 1.7.0 |
| Created-By: 1.5.0_13-119 (Apple Inc.) |
| Bundle-ManifestVersion: 2 |
| Bundle-SymbolicName: org.springframework.showcase.formtags.web-shared- |
| services |
| Import-Package: org.springframework.showcase.formtags.domain,org.sprin |
| gframework.showcase.formtags.service, org.eclipse.virgo.web.dm;version="[1.0,2.1)" |
| Import-Library: org.springframework.spring;version="[2.5.4,3.1.0)" |
| Import-Bundle: com.springsource.org.apache.taglibs.standard;version="1 |
| .1.2",org.springframework.osgi.core</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In addition to importing the exported types of the service bundle, |
| the WAR must also obtain a reference to the |
| <code>UserManager</code> |
| published by the service bundle. The following image shows the |
| directory |
| structure of the Shared Services WAR.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/formtags-case-study-shared-services-war-resources.png" alt="formtags case study shared services war resources"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>As you can see in the above image, the Form Tags Shared Services |
| WAR’s |
| <code>/WEB-INF/web.xml</code> |
| directory contains a standard |
| <code>web.xml</code> |
| deployment descriptor, |
| <code>applicationContext.xml</code> |
| which defines the configuration |
| for the |
| <strong>root</strong> |
| <code>WebApplicationContext</code> |
| , and |
| <code>formtags-servlet.xml</code> |
| which defines the configuration specific to the |
| configured |
| <strong>formtags</strong> |
| <code>DispatcherServlet</code> |
| .</p> |
| </div> |
| <div class="paragraph"> |
| <p>As is typical for Spring MVC based web applications, you configure a |
| <code>ContextLoaderListener</code> |
| in |
| <code>web.xml</code> |
| to load your root |
| <code>WebApplicationContext</code> |
| ; however, to enable your |
| <code>WebApplicationContext</code> |
| to be able to reference services from the OSGi Service Registry, |
| you |
| must explicitly set the |
| <code>contextClass</code> |
| Servlet context parameter to the fully qualified |
| class name of a |
| <code>ConfigurableWebApplicationContext</code> |
| which is OSGi-enabled. When deploying |
| Shared Services WARs to the |
| Virgo for Apache Tomcat, you should use |
| <code>org.eclipse.virgo.web.dm.ServerOsgiBundleXmlWebApplicationContext</code>. |
| This will then enable the use of Gemini Blueprint’s <code><reference …​ /></code> |
| within your root <code>WebApplicationContext</code> (i.e., in <code>applicationContext.xml</code>). |
| The following listing is an excerpt from <code>/WEB-INF/web.xml</code>.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"><context-param> |
| <param-name>contextClass</param-name> |
| <param-value>org.eclipse.virgo.web.dm.ServerOsgiBundleXmlWebApplicationContext</param-value> |
| </context-param> |
| |
| <listener> |
| <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class> |
| </listener></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The Form Tags Shared Services WAR contains a |
| <code>/WEB-INF/applicationContext.xml</code> |
| file which is the default configuration location used to create the |
| <strong>root</strong> |
| <code>WebApplicationContext</code> |
| for Spring MVC’s |
| <code>ContextLoaderListener</code>.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>As already mentioned, in the OSGi world, bundle configuration |
| takes |
| place in the root |
| <code>/META-INF/</code> |
| directory. |
| Typically Gemini Blueprint powered configuration files will live |
| there as well (e.g., in |
| <code>/META-INF/spring/*.xml</code> |
| ). |
| In a WAR, however, the root |
| <code>WebApplicationContext</code> |
| loaded by |
| <code>ContextLoaderListener</code> |
| and the |
| <code>DispatcherServlet’s</code> |
| application context typically live in |
| <code>/WEB-INF/</code>.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The following is the listing of the WAR’s |
| <code>/WEB-INF/applicationContext.xml</code>.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> |
| <beans:beans |
| xmlns="http://www.springframework.org/schema/osgi" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xmlns:beans="http://www.springframework.org/schema/beans" |
| xsi:schemaLocation="http://www.springframework.org/schema/osgi |
| http://www.springframework.org/schema/osgi/spring-osgi.xsd |
| http://www.springframework.org/schema/beans |
| http://www.springframework.org/schema/beans/spring-beans.xsd"> |
| |
| <reference id="userManager" |
| interface="org.springframework.showcase.formtags.service.UserManager"/> |
| |
| </beans:beans></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The single bean declaration is retrieving a service that implements |
| the |
| `org.springframework.showcase.formtags.service.UserManager |
| ` |
| API from the OSGi Service Registry.</p> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Tip</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>You might have been expecting a reference to the service bundle, |
| but that isn’t how OSGi works. OSGi provides a service |
| registry, and this bean definition is accessing a service in that |
| registry that meets the specified restriction (i.e. implements |
| the |
| specified interface). This leads to a very loosely coupled |
| programming model: the WAR really doesn’t care where the |
| implementation |
| comes from.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Tip</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>What happens if there is no service at runtime? |
| What if there are |
| multiple services that match the criteria? |
| Gemini Blueprint provides a lot |
| of configuration options, including |
| whether or not the reference is |
| <strong>mandatory</strong> |
| , |
| how long to wait for a service reference, etc. Please consult the |
| <a href="https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html">Eclipse Gemini Blueprint Reference Guide</a> for further information.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>One of the benefits of programming to interfaces is that you |
| are |
| decoupled from the actual implementation; Gemini Blueprint provides a |
| proxy. This |
| has enormous benefits including the ability to |
| dynamically refresh individual bundles without |
| cascading that |
| refresh to unrelated bundles.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To deploy the WAR, copy |
| <code>/dist/formtags-shared-services-war*</code> |
| to the |
| <code>SERVER_HOME/pickup</code> |
| directory. |
| You should then see console output similar to the |
| following:</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>The console output has been reformatted to fit this document.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">[2009-07-01 15:09:19.819] fs-watcher |
| <SPDE0048I> Processing 'CREATED' event for file 'formtags-shared-services-war-3.0.0.RELEASE.war'. |
| [2009-07-01 15:09:20.167] fs-watcher |
| <SPDE0010I> Deployment of 'org.springframework.showcase.formtags.web_shared_services' version '3' completed. |
| [2009-07-01 15:09:20.168] Thread-20 |
| <SPWE0000I> Starting web bundle '/formtags-shared-services-war-3.0.0.RELEASE'. |
| [2009-07-01 15:09:20.647] Thread-20 |
| <SPWE0001I> Started web bundle '/formtags-shared-services-war-3.0.0.RELEASE'. |
| ----</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Navigating to the appropriate link should render the welcome page.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="formtags-case-study-par"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_form_tags_par">Form Tags PAR</h3> |
| <div class="paragraph"> |
| <p>The final step in the migration is that of a full blown |
| OSGi |
| application with web support. The Virgo for Apache Tomcat introduces a |
| new packaging and deployment format: the PAR.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A PAR is a standard JAR with a “.par” |
| file extension which contains all of the modules of your |
| application (e.g., service, domain, and infrastructure bundles |
| as well |
| as a WAR for web applications) in a single deployment unit. |
| Moreover, |
| a PAR defines both a physical and logical application boundary.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The PAR sample is comprised of four directories, as shown below.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/formtags-case-study-par-sample.png" alt="formtags case study par sample"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>The |
| <code>formtags-par</code> |
| directory is a build project that |
| understands how to create the PAR |
| from its constituent bundles.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="formtags-case-study-par-granularity"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_granularity_of_the_par">Granularity of the PAR</h4> |
| <div class="paragraph"> |
| <p>Achieving the appropriate level of granularity for your OSGi |
| application is more of an art than a science. It helps to look |
| at the |
| different requirements:</p> |
| </div> |
| <table class="tableblock frame-all grid-all spread"> |
| <caption class="title">Table 6. Granularity drivers</caption> |
| <colgroup> |
| <col style="width: 40%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Requirement</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Domain/Technical Layering</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Applications can be split either by domain (i.e., |
| by use case or |
| <strong>vertically</strong> |
| ) or |
| by their technical layers (i.e., |
| <strong>horizontally</strong> |
| ). |
| Since the Form Tags application essentially has only |
| a single |
| use case, the bundles are split by technical layering |
| (i.e., |
| domain, service, and web).</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Refreshability</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">A major benefit of OSGi is that of refreshability: if one |
| bundle |
| is changed, only bundles that have a dependency upon |
| the |
| exported types need to be refreshed. This has a high impact |
| on |
| development time costs as well as production |
| costs. However, |
| this can lead to lots of smaller, fine grained |
| bundles. An |
| example of this granularity would be to |
| separate out the service |
| API and implementation into two different |
| bundles. This means |
| that a change in the implementation |
| wouldn’t require any |
| other bundles to be refreshed.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Ultimately the right level of granularity will depend upon your |
| particular application and team.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="formtags-case-study-par-domain-and-service"></a></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="_domain_and_service_bundles">Domain and Service Bundles</h4> |
| <div class="paragraph"> |
| <p>The service bundle is identical (except for the |
| <code>Bundle-SymbolicName</code> |
| ) to that |
| in the shared-services variation of the sample. |
| The PAR has |
| also separated out the domain classes into their own bundle. |
| When |
| layering by technical considerations, it is again |
| somewhat of an |
| unofficial convention to have a |
| <code>.domain</code> |
| bundle.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="formtags-case-study-par-par"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_constructing_the_par">Constructing the PAR</h3> |
| <div class="paragraph"> |
| <p>Finally we need to construct the PAR itself. |
| The following are |
| the contents of the exploded PAR.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="assets/images/formtags-case-study-par-exploded.png" alt="formtags case study par exploded"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>You can see that the PAR itself doesn’t contain any |
| resources or |
| Java classes: it simply packages together a related set |
| of bundles |
| as a single, logical unit.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The PAR does however, contain its own |
| <code>/META-INF/MANIFEST.MF</code>.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">Manifest-Version: 1.0 |
| Application-SymbolicName: org.springframework.showcase.formtags-par |
| Application-Version: 3.0.0 |
| Application-Name: FormTags Showcase Application (PAR)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>For more information on the contents of the PAR’s |
| <code>/META-INF/MANIFEST.MF</code> |
| , please consult <a href="#developing-applications">Developing Applications</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You can now deploy the PAR on the VTS, for |
| example by copying |
| <code>/dist/formtags-par*.par</code> |
| to the VTS’s |
| <code>pickup</code> |
| directory. |
| You should then see console output similar to the |
| following:</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>The console output has been reformatted to fit this document.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">[2009-07-01 15:13:43.306] fs-watcher |
| <SPDE0048I> Processing 'CREATED' event for file 'formtags-par-2.0.0.RELEASE.par'. |
| [2009-07-01 15:13:44.060] fs-watcher |
| <SPDE0010I> Deployment of 'formtags-par' version '2.0.0.RELEASE' completed. |
| [2009-07-01 15:13:44.068] Thread-20 |
| <SPWE0000I> Starting web bundle '/formtags-par'. |
| [2009-07-01 15:13:45.212] Thread-20 |
| <SPWE0001I> Started web bundle '/formtags-par'.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Navigate to <a href="http://localhost:8080/formtags-par" class="bare">http://localhost:8080/formtags-par</a> to see the welcome page.</p> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Tip</div> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Note that the web application’s context path is explicitly |
| defined via the |
| <code>Web-ContextPath</code> |
| manifest header in |
| <code>/META-INF/MANIFEST.MF</code> |
| of the Web application bundle within the PAR.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><a id="formtags-case-study-summary"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_summary_of_the_form_tags_migration">Summary of the Form Tags Migration</h3> |
| <div class="paragraph"> |
| <p>The Virgo for Apache Tomcat provides out-of-the-box support for |
| deploying |
| standard Java EE WAR files. In addition support for |
| <strong>Shared Libraries</strong> |
| and |
| <strong>Shared Services</strong> |
| WAR formats provides a logical migration path away from standard, |
| monolithic WARs toward OSGi-enable Web applications. The PAR |
| packaging |
| and deployment format enables truly fine-grained, |
| loosely-coupled, and |
| efficient application development. In general, |
| the migration steps |
| presented in this chapter are fairly |
| straightforward, but developers |
| should set aside time for some |
| up-front design of the bundles themselves.</p> |
| </div> |
| <div class="paragraph"> |
| <p>It is recommended that you take another sample application or |
| indeed your own small application and go through this migration |
| process yourself. This will help you better understand the concepts |
| and |
| principles at work. In addition, it is highly recommended that you |
| familiarize yourself with the extensive Eclipse IDE support provided |
| by the Virgo Tools. See the Virgo Tools Guide for more on that.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="formtags-case-study-as-plan"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_form_tags_as_a_plan">Form Tags as a Plan</h3> |
| <div class="paragraph"> |
| <p>Plans (see <a href="#developing-applications-plans">Creating Plans</a>) |
| allow us to package and deploy the Form Tags application in a more |
| flexible way. |
| Instead of packaging all the bundles of the application |
| into a single PAR file, each bundle can be placed in the repository |
| and referred to in a <strong>plan</strong>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The bundles to be placed in a repository in the chain (for example, |
| <code>repository/usr</code>) are:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">org.springframework.showcase.formtags.domain-2.0.0.RELEASE.jar |
| org.springframework.showcase.formtags.service-2.0.0.RELEASE.jar |
| org.springframework.showcase.formtags.web-2.0.0.RELEASE.war</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>which are just those files which were part of the PAR.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Here is the contents of a suitable plan file for the Form Tags |
| example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-xml" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> |
| <plan name="formtags.plan" version="2.0.0" scoped="true" atomic="true" |
| xmlns="http://www.eclipse.org/virgo/schema/plan" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation=" |
| http://www.eclipse.org/virgo/schema/plan |
| http://www.eclipse.org/virgo/schema/plan/eclipse-virgo-plan.xsd"> |
| |
| <artifact type="bundle" name="org.springframework.showcase.formtags.domain_par" version="[3.0,3.1)"/> |
| <artifact type="bundle" name="org.springframework.showcase.formtags.service_par" version="[3.0,3.1)"/> |
| <artifact type="bundle" name="org.springframework.showcase.formtags.web_par" version="[3.0,3.1)"/> |
| |
| </plan></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>where we have chosen to use any of the artifacts in the version range [2.0,2.1). |
| This plan (as a file called, for example, <code>formtags.plan</code>) |
| can be deployed in any of the normal ways (for example, dropped in the <code>pickup</code> directory).</p> |
| </div> |
| <div class="paragraph"> |
| <p>When the plan is deployed, the artifacts it references are |
| installed from the repository and deployed in the order given in the |
| plan file. |
| Because this plan is scoped and atomic, the collection is |
| given an application scope and is started and stopped as a single |
| unit.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="common-libraries"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_working_with_common_enterprise_libraries">Working with Common Enterprise Libraries</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Common Libraries</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="common-libraries-hibernate"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_working_with_hibernate">Working with Hibernate</h3> |
| <div class="paragraph"> |
| <p><a id="common-libraries-hibernate-import"></a></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="_importing_hibernate">Importing Hibernate</h4> |
| <div class="paragraph"> |
| <p>Hibernate uses CGLIB to dynamically create subclasses of your entity types at |
| runtime. To guarantee that Hibernate and CGLIB can correctly see the types, |
| you must add an <code>Import-Library</code> or <code>Import-Bundle</code> for the Hibernate library or bundle |
| into any bundle that uses Hibernate directly.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Additionally, if other bundles in your application contain types to be persisted by Hibernate, then be sure to specify the <code>import-scope</code> directive of the <code>Import-Bundle</code> header in the bundle that uses Hibernate directly. The <code>import-scope</code> directive tells Virgo for Apache Tomcat to implicitly import the bundle into all other bundles that make up the application; this ensures that bundles that indirectly depend on the generated Hibernate classes have access to them, but you do not have to explicitly update their <code>Import-Bundle</code> header, ensuring modularity. For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">Import-Bundle: com.springsource.org.hibernate;version="[3.2.6.ga,3.2.6.ga]";import-scope:=application</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>import-scope</code> directive works only for the bundles in a scoped application (PARs or plans.)</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="common-libraries-datasources"></a></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_working_with_datasources">Working with DataSources</h3> |
| <div class="paragraph"> |
| <p>Many <code>DataSource</code> implementations use the <code>DriverManager</code> |
| class which is incompatible with typical OSGi class loading semantics. To get around this, |
| use a <code>DataSource</code> implementation that does not rely on |
| <code>DriverManager</code>. Versions of the following |
| <code>DataSources</code> that are known to work in an OSGi environment are available in the |
| <a href="http://www.eclipse.org/ebr">EBR</a>.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="http://build.eclipse.org/rt/virgo/ivy/bundles/release/org.eclipse.virgo.mirrored/org.apache.commons.dbcp/">Apache Commons DBCP</a></p> |
| </li> |
| <li> |
| <p>SimpleDriverDataSource available in <a href="http://build.eclipse.org/rt/virgo/ivy/bundles/release/org.eclipse.virgo.mirrored/org.springframework.jdbc/">Spring JDBC</a> 2.5.5 and later</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a id="common-libraries-weaving-instrumentation"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_weaving_and_instrumentation">Weaving and Instrumentation</h3> |
| <div class="paragraph"> |
| <p>When using a library that performs bytecode weaving or instrumentation, such as AspectJ, |
| OpenJPA or EclipseLink, any types that are woven must be able to see the library doing |
| the weaving. This is accomplished by adding an <code>Import-Library</code> for the |
| weaving library into all bundles that are to be woven.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Weaving is often used by JPA implementations to transform persisted types. When using a |
| JPA provider that uses load-time weaving, an <code>Import-Library</code> for the |
| provider is needed in the bundles containing the persisted types.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="common-libraries-tld"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_jsp_tag_libraries">JSP Tag Libraries</h3> |
| <div class="paragraph"> |
| <p>When using tag libraries within a WAR or WAB, be sure to include an <code>Import-Bundle</code> |
| or <code>Import-Library</code> for the tag library bundle(s). This will ensure that your WAR or WAB |
| can see the TLD definition and implementing types. For example, to use the Apache implementation of JSTL, |
| add the following to your bundle’s <code>/META-INF/MANIFEST.MF</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-txt" data-lang="txt">Import-Bundle: com.springsource.org.apache.taglibs.standard;version="1.1.2"</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><code>Import-Package</code> can also be used but it is tedious to add all the imports as there are |
| typically lots of tld definitions in a bundle providing them.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="known-issues"></a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_known_issues">Known Issues</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><a id="known-issues-jpa"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_jpa_entity_scanning">JPA Entity Scanning</h3> |
| <div class="paragraph"> |
| <p>Classpath scanning for JPA entities annotated with <code>@Entity</code> does |
| not work. Describing entities with <code>@Entity</code> will work, but the |
| entities need to be listed explicitly.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="known.issues.proxy"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="__code_classnotfounderror_code_when_creating_a_proxy"><code>ClassNotFoundError</code> When Creating a Proxy</h3> |
| <div class="paragraph"> |
| <p>When creating proxies at runtime, there are circumstances where <code>ClassNotFoundErrors</code> |
| can be generated. These errors happen because the proxy creating bundle does not have visibility into every |
| type on the interface of the proxy. You can either put in import statements for all the relevant types or |
| add use a service (with visibility of all pertinent types) to create the proxy. Please see |
| <a href="http://www.osgi.org/blog/2008/08/classy-solutions-to-tricky-proxies.html">this blog entry</a> |
| for more details.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="known.issues.cglib"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_creating_proxies_with_cglib_for_package_protected_types">Creating proxies with CGLIB for Package Protected Types</h3> |
| <div class="paragraph"> |
| <p>In traditional Java EE applications user types are loaded by the same <code>ClassLoader</code> as |
| CGLIB. This allows CGLIB to proxy package-protected types. In OSGi environments, user types and CGLIB will |
| most likely be packaged in separate bundles. This results in the user types and CGLIB being loaded by |
| different <code>ClassLoaders</code>. This prevents CGLIB from proxying any package-protected types.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The workaround for this issue is to make all types that require proxying public.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="known-issues-jetty-restrictions"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_virgo_jetty_server_restrictions">Virgo Jetty Server Restrictions</h3> |
| <div class="paragraph"> |
| <p>The following Jetty features are not supported.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Tag Libraries other than the standard Apache Tag Library.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p><a id="known-issues-web-bundle-default-headers"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_default_web_application_bundle_headers">Default Web Application Bundle Headers</h3> |
| <div class="paragraph"> |
| <p>The Gemini Web container conforms to the OSGi Web Applications specification and does not apply default values |
| to the headers of a Web Application Bundle. However, SpringSource dm Server 2.0.x applies default values |
| to certain headers (see <a href="#developing-applications-automatic-imports-web">Web Application Manifest |
| Processing</a> for details) and so Virgo Web Server 2.1.x modified the behaviour of Gemini Web so that it applied default |
| values consistently with dm Server 2.0.x.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This behaviour is changed as of Virgo for Apache Tomcat 3.0. VTS now conforms strictly to the |
| OSGi Web Applications specification.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As a migration aid, <strong>which may not be supported in a future release</strong>, users may configure the VTS Web Integration |
| Layer to apply default values to the headers of a Web Application Bundle. |
| See "Configuring the Web Integration Layer" in the <a href="../../virgo-user-guide/html/index.html">User Guide</a> for details.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="hibernate-resolution-issue"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_hibernate_resolution_issue">Hibernate Resolution Issue</h3> |
| <div class="paragraph"> |
| <p>Applications using Hibernate 3.4.0.GA need to upgrade the JBoss Hibernate Entity manager fragment bundle to version 3.4.0.GA-A. |
| The symptoms are that the application will fail to resolve due to missing imports of packages such as <code>org.hibernate.ejb.transaction</code> |
| and JBoss Hibernate Annotations <code>com.springsource.org.hibernate.annotations</code>. |
| See <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=335174">bug 335174</a> for details.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The JBoss Hibernate Entity manager fragment bundle <code>com.springsource.org.hibernate.ejb</code> v3.4.0.GA in the |
| <a href="http://ebr.springsource.com/repository/app/">SpringSource Enterprise Bundle Repository</a> |
| depends on the package <code>org.slf4j</code> with a version range that excludes the version of the |
| package provided with Virgo. The net effect is that Hibernate EJB fragment bundle fails to attach to its host |
| <code>com.springsource.org.hibernate</code> and the host then does not export the packages the application |
| may need, such as <code>org.hibernate.ejb.transaction</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An updated JBoss Hibernate Entity manager fragment and JBoss Hibernate Annotations with versions 3.4.0.GA-A which fixes this |
| problem is available from the <a href="http://ebr.springsource.com/repository/app/">SpringSource Enterprise Bundle Repository</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="scoping-and-substitutable-exports"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_scoping_and_substitutable_exports">Scoping and Substitutable Exports</h3> |
| <div class="paragraph"> |
| <p>The restriction described in <a href="#developing-applications-plans-scoping">Plans and Scoping</a> that |
| no package may be exported by more than one bundle in a given scope can cause problems for bundles with |
| <strong>substitutable exports</strong>. A substitutable export is a package which is exported and imported |
| by the same bundle. The OSGi framework will discard either the import or the export of the package when the |
| bundle is resolved.</p> |
| </div> |
| <div class="paragraph"> |
| <p>However, if more than one bundle in a scope has a substitutable export of the same package, then Virgo will fail |
| to deploy the scoped application because the above restriction appears to be broken. Virgo could only spot that |
| the restriction was not actually being broken by second guessing the resolution behaviour of the OSGi framework, |
| something that Virgo generally avoids because of the fragility of that approach.</p> |
| </div> |
| <div class="paragraph"> |
| <p>It may be possible to work around this issue by omitting one of the bundles containing the substitutable export |
| from the scoped application.</p> |
| </div> |
| <div class="paragraph"> |
| <p>It may also be possible to work around this issue by moving the bundles containing the substitutable exports outside the scope, |
| although this will not give correct behaviour if the bundles' exported packages need to be available for thread |
| context class loading.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=330643">bug 330643</a> for an example of this issue.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="eclipselink-resolution-issue"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_eclipselink_resolution_issue">EclipseLink Resolution Issue</h3> |
| <div class="paragraph"> |
| <p>Applications using EclipseLink may fail to resolve if the <code>osgi.enterprise</code> bundle is allowed to |
| wire its <code>javax.persistence</code> package import to other than the EclipseLink <code>javax.persistence</code> bundle.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To avoid this, install EclipseLink’s <code>javax.persistence</code> bundle early. To install this bundle before |
| any applications are deployed, list the bundle in the <code>initialArtifacts</code> property described in the |
| <a href="../../virgo-user-guide/html/index.html">User Guide</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=337826">bug 337826</a> for details.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div id="footer"> |
| <div id="footer-text"> |
| Last updated 2017-02-23 21:06:43 +01:00 |
| </div> |
| </div> |
| </body> |
| </html> |
