Google Git
Sign in
eclipse / gerrit / www.eclipse.org / virgo / 7d2ad7dbbfbad755c2a31fb78e6889ed084a0509 / . / documentation / virgo-documentation-3.7.0.RC01 / docs / virgo-user-guide / html5 / concepts.html
blob: bdcb60ed6dbc4371d352b7a3072c5b85d6a40c3d [file] [log] [blame]
<!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>Concepts</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">
</div>
<div id="content">
<div class="paragraph">
<p><a id="concepts"></a></p>
</div>
<div class="sect1">
<h2 id="_concepts">Concepts</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This chapter introduces some basic concepts that will help you to use Virgo.</p>
</div>
<div class="paragraph">
<p><a id="concepts.modular"></a></p>
</div>
<div class="sect2">
<h3 id="_modular_runtimes_and_applications">Modular Runtimes and Applications</h3>
<div class="paragraph">
<p>Virgo for Apache Tomcat, Virgo Jetty Server, Virgo Kernel and Virgo Nano are Java runtimes each composed of
a collection of modules and supporting applications which are also composed of a
collection of modules.
Modules can be shared between applications and multiple versions of modules
can co-exist.</p>
</div>
<div class="paragraph">
<p><a id="concepts.osgi"></a></p>
</div>
</div>
<div class="sect2">
<h3 id="_osgi_concepts">OSGi Concepts</h3>
<div class="paragraph">
<p>Modules in Virgo are represented using a standard Java
module system known as <strong>OSGi</strong>.
Modules in OSGi are known as <strong>bundles</strong>.
Bundles consist of programs and resources organised by Java package together
with metadata which declares imported and exported packages.
A bundle <strong>exports</strong> a package to make the corresponding programs and resources
available for use by other bundles.
A bundle <strong>imports</strong> a package to use the corresponding programs and resources of
another bundle.</p>
</div>
<div class="paragraph">
<p>Representing a program as a collection of bundles makes it easier for the
programmer to manage it and modify it and for teams of programmers to divide
responsibilities between themselves.
A bundle is similar to a Java class in this respect. Design principles similar to those for
organising data and programs into classes can be applied
to organising applications into bundles.</p>
</div>
<div class="paragraph">
<p>An industry consortium known as the
<strong>OSGi Alliance</strong> develops OSGi
specifications, reference implementations, and compliance tests.
Virgo is built on the Equinox OSGi framework which is also
the reference implementation for the OSGi framework specification.</p>
</div>
<div class="sect3">
<h4 id="_bundles">Bundles</h4>
<div class="paragraph">
<p>Each bundle is stored in a file which conforms to the JAR file format and
can contain Java classes, a manifest (in <code>META-INF/MANIFEST.MF</code>),
and further resource files.</p>
</div>
<div class="paragraph">
<p>The OSGi framework enables bundles to be installed and run.</p>
</div>
<div class="paragraph">
<p>OSGi identifies bundles "by name" and "by identifier" (id).</p>
</div>
<div class="paragraph">
<p>The <strong>symbolic name</strong> and
<strong>version</strong> of a bundle are attributes of the bundle which identify the bundle.
A bundle declares its <strong>symbolic name</strong> and <strong>version</strong>
in its manifest (a file called <code>MANIFEST.MF</code>) like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-txt" data-lang="txt">Bundle-SymbolicName: org.foo.bundle
Bundle-Version: 1.2.3.BUILD-2009-06-04</code></pre>
</div>
</div>
<div class="paragraph">
<p>Additionally, the OSGi framework
assigns a distinct number, known as a <strong>bundle id</strong>, to each bundle
as it is installed. Bundles may be referred to "by identifier" using this number.
The OSGi framework itself resides in a
bundle with bundle id <code>0</code>.</p>
</div>
<div class="paragraph">
<p>The dependencies between bundles are expressed statically in terms of packages and
dynamically in terms of services. A package is familiar to Java programmers.
For example, a Java program may depend on a class <code>org.foo.X</code>,
from package <code>org.foo</code>, and a bundle
containing that program
would either need to contain <code>org.foo.X</code> or depend on the
package <code>org.foo</code>.
Package dependencies are specified in the bundle manifest, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-txt" data-lang="txt">Import-Package: org.foo</code></pre>
</div>
</div>
<div class="paragraph">
<p>A bundle which provides a package for use by other bundles <strong>must</strong>
export the package in its manifest. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-txt" data-lang="txt">Export-Package: org.foo</code></pre>
</div>
</div>
<div class="paragraph">
<p>The OSGi framework ensures that a given bundle&#8217;s package dependencies
can be <strong>satisfied</strong> before the bundle runs. This process is known as
<strong>resolution</strong>.</p>
</div>
<div class="paragraph">
<p>After a bundle is resolved, its classes and resources are available for
loading.
In OSGi, bundles and their packages do not appear on the application classpath.
Instead, each bundle has a class loader which loads its own classes and loads classes belonging to each of its
imported packages by deferring to the bundle class loader that exports the package.</p>
</div>
</div>
<div class="sect3">
<h4 id="_life_cycle">Life Cycle</h4>
<div class="paragraph">
<p>The OSGi framework manages the <strong>life cycle</strong> of each bundle. A bundle is
first of all <strong>installed</strong> and will be in the INSTALLED state.
If a request is made to <strong>start</strong> the bundle, the OSGi framework <strong>resolves</strong> the bundle
and, if resolution was successful, will subsequently move the bundle to the ACTIVE state.
If a request is made to <strong>stop</strong> the bundle, the OSGi framework will move the
bundle back to the RESOLVED state. A request may then be made to <strong>uninstall</strong>
the bundle.</p>
</div>
<div class="paragraph">
<p>While the bundle is INSTALLED, ACTIVE or RESOLVED, it may be <strong>updated</strong> to pick up
some changes. These changes are not detected by bundles which were depending
on the bundle before it was updated.
A "refresh packages" operation may be performed to ripple the
changes out to those bundles. (See <a href="#concepts.services">Services concepts</a>.)
The life cycle of a bundle can be summarised by a state transition diagram.
This diagram shows some more of the intermediate states of a bundle not described in the overview above:</p>
</div>
<div class="paragraph">
<div class="title">Bundle life cycle</div>
<p><span class="image center"><img src="assets/images/concepts/bundle-lifecycle.png" alt="bundle lifecycle"></span></p>
</div>
<div class="paragraph">
<p><a id="concepts.services"></a></p>
</div>
</div>
<div class="sect3">
<h4 id="_services">Services</h4>
<div class="paragraph">
<p>Bundles may publish Java objects, known as <strong>services</strong>,
to a registry managed by the OSGi framework. Other bundles running in
the same OSGi framework can then find and use those services. Services
are typically instances of some shared Java interface. A bundle which
provides a service need not then export the package containing the
<strong>implementation</strong>
class of the service.</p>
</div>
<div class="paragraph">
<p>For example, a bundle could export a package containing the interface
<code>org.bar.SomeInterface</code>, thus:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-txt" data-lang="txt">Export-Package: org.bar</code></pre>
</div>
</div>
<div class="paragraph">
<p>…implement the interface with a class <code>SomeImpl</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">package org.bar.impl;
class SomeImpl implements SomeInterface {
…
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>…create an instance of <code>SomeImpl</code> and
then publish this instance (as an instance of the interface <code>SomeInterface</code>).</p>
</div>
<div class="paragraph">
<p>An OSGi framework publishes a number of standard services. For example, the
<strong>Package Admin</strong> service provides the "refresh packages" life cycle operation
mentioned above.</p>
</div>
<div class="paragraph">
<p>OSGi provides an <strong>API</strong> which can be used to publish and find services,
but it is much simpler to use Blueprint to accomplish this. (See <a href="#concepts.blueprint">Gemini Blueprint</a>.)</p>
</div>
</div>
<div class="sect3">
<h4 id="_versioning">Versioning</h4>
<div class="paragraph">
<p>OSGi allows different versions of bundles, packages, and several
other entities, to co-exist in the same framework
and provides some mechanisms for managing these versions.</p>
</div>
</div>
<div class="sect3">
<h4 id="_version_numbers">Version Numbers</h4>
<div class="paragraph">
<p>An OSGi <strong>version number</strong> consists of up to three numeric components,
or exactly three
numeric components followed by a string component. These components are
separated by a period (&#8220;.&#8221;) and
are called the <strong>major</strong>, <strong>minor</strong>, <strong>micro</strong>,
and <strong>qualifier</strong> components, respectively.</p>
</div>
<div class="paragraph">
<p>For example, the version <code>2.4.1.ga</code> has major component <code>2</code>, minor component
<code>4</code>, micro component <code>1</code>,
and a qualifier component <code>ga</code>. (There are restrictions on the characters that can appear in
a qualifier. For example: letters, digits, underscores and hyphens are allowed; periods and commas are not.)</p>
</div>
<div class="paragraph">
<p>Trailing components may be omitted along with their period (<code>.</code>). So, for example, the version
numbers <code>2</code>, <code>2.0</code>, and <code>2.0.0</code>
all denote the same version. This example demonstrates that <code>0</code> is assumed if a numeric component is omitted,
and the empty string is assumed for an omitted qualifier.</p>
</div>
</div>
<div class="sect3">
<h4 id="_version_ranges">Version Ranges</h4>
<div class="paragraph">
<p>Dependencies on bundles and packages have an associated <strong>version range</strong>
which is specified using an interval notation: a square bracket
&#8220;[&#8221; or &#8220;]&#8221; denotes
an <strong>inclusive</strong> end of the range and a round bracket
&#8220;(&#8221; or &#8220;)&#8221; denotes
an <strong>exclusive</strong> end of the range. Where one end of the range is to be included and the other excluded, it is permitted to
pair a round bracket with a square bracket.
The examples below make this clear.</p>
</div>
<div class="paragraph">
<p>If a single version number is used where a version <strong>range</strong> is
required this does <strong>not</strong> indicate a single version, but the range <strong>starting</strong> from that version and
including all higher versions.</p>
</div>
<div class="paragraph">
<p>There are three common cases:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A "strict" version range, such as <code>[1.2,1.2]</code>, which
denotes that version and only that version.</p>
</li>
<li>
<p>A "half-open" range, such as
<code>[1.2,2)</code>, which has an inclusive lower limit
and an exclusive upper limit, denoting version <code>1.2.0</code> and any version after this, up
to, <strong>but not including</strong>, version <code>2.0.0</code>.</p>
</li>
<li>
<p>An "unbounded" version range, such as <code>1.2</code>, which
denotes version <code>1.2</code> and <strong>all</strong> later versions.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_versioning_policies">Versioning Policies</h4>
<div class="paragraph">
<p>A <strong>versioning policy</strong> is a way of using version numbers to indicate compatible
and incompatible changes.
OSGi does not mandate a particular versioning policy.
Instead, a specific versioning policy may be implemented using version ranges.
Strict and half-open version ranges are most useful in representing versioning
policies.
Unbounded version ranges can lead to problems as they (unrealistically) assume that
compatibility will be preserved indefinitely.</p>
</div>
<div class="paragraph">
<p>For example, a conservative versioning policy might assume that any change, other than
in the qualifier component of a version, implies an incompatible
change to the object.
Such a policy would employ version ranges such as <code>[1.2.1.beta,1.2.2)</code>
which accept any version from <code>1.2.1.beta</code> (inclusive) up to but not including
<code>1.2.2</code> (exclusive).</p>
</div>
<div class="paragraph">
<p>Alternatively, a relaxed versioning policy might assume that only changes in the major component of
a version denote an incompatible change.
Such a policy would employ version ranges such as <code>[1.2,2)</code> to capture this.</p>
</div>
<div class="paragraph">
<p>The OSGi Alliance has published a <a href="http://www.osgi.org/wiki/uploads/Links/SemanticVersioning.pdf">Semantic
Versioning white paper</a> which provides some recommendations and guidance on versioning policies.</p>
</div>
</div>
<div class="sect3">
<h4 id="_bundle_version">Bundle Version</h4>
<div class="paragraph">
<p>Each bundle has a version.
The bundle&#8217;s version may be specified in the manifest using a
<code>Bundle-Version</code> header:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>Bundle-Version: 1.4.3.BUILD-20090302</pre>
</div>
</div>
<div class="paragraph">
<p>If not specified the bundle version is assumed to be <code>0</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_package_version">Package Version</h4>
<div class="paragraph">
<p>Each exported package has a version.
The exported package&#8217;s version may be specified on the Export-Package manifest header. For example</p>
</div>
<div class="literalblock">
<div class="content">
<pre>Export-Package: org.foo;version="2.9",org.bar;version="1"</pre>
</div>
</div>
<div class="paragraph">
<p>exports two packages: <code>org.foo</code>, at version <code>2.9.0</code> and
<code>org.bar</code>, at version <code>1.0.0</code>.</p>
</div>
<div class="paragraph">
<p>If the version attribute is omitted, the version is assumed to be <code>0</code>.</p>
</div>
<div class="paragraph">
<p>Each package <strong>import</strong> has a version <strong>range</strong>.
The package import version range may be specified on the <code>Import-Package</code> manifest header.
If interval notation is used, the version range must be enclosed in double quotes, for example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>Import-Package: org.foo;version="[2,3)",org.bar;version="[1,1]"&lt;/programlisting&gt;</pre>
</div>
</div>
<div class="paragraph">
<p>seeks to import a package <code>org.foo</code> in the range <code>[2.0.0,3.0.0)</code> and a package
<code>org.bar</code> with the (exact) version <code>1.0.0</code>.</p>
</div>
<div class="paragraph">
<p>If a version range is not specified on an import, the range <code>0</code> is assumed, meaning that
any version of this package would satisfy the import.</p>
</div>
</div>
<div class="sect3">
<h4 id="_bundle_manifest_version">Bundle Manifest Version</h4>
<div class="paragraph">
<p>Bundle manifests have a version which is <code>1</code> by default,
indicating OSGi Release 3 semantics.
Virgo is based on OSGi Release 4 and therefore expects bundle manifests to be
at version <code>2</code>, indicating OSGi Release 4 semantics.
The bundle manifest&#8217;s version should be specified on the Bundle-ManifestVersion manifest header, exactly as follows:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>Bundle-ManifestVersion: 2</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_manifest_version">Manifest Version</h4>
<div class="paragraph">
<p>Manifests themselves also have a version which <strong>must</strong> be specified as <code>1.0</code>.
This is not an OSGi definition but part of the
(<a href="http://docs.oracle.com/javase/6/docs/technotes/guides/jar/jar.html">JAR file specification</a>).</p>
</div>
<div class="literalblock">
<div class="content">
<pre>Manifest-Version: 1.0</pre>
</div>
</div>
<div class="paragraph">
<p><a id="concepts.blueprint"></a></p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_blueprint_concepts">Blueprint Concepts</h3>
<div class="paragraph">
<p>Spring DM (the predecessor of Gemini Bluprint) is a project which enables <strong>services</strong> to be published and consumed
using descriptions written in XML.</p>
</div>
<div class="paragraph">
<p>The XML descriptions reside in files with extension <code>.xml</code> in the
bundle&#8217;s <code>META-INF/spring</code> sub-directory.</p>
</div>
<div class="paragraph">
<p>To publish a service, an <code>&lt;osgi:service&gt;</code> tag is used, specifying the
implementation class of the service and the interface class to be used.
Spring DM constructs an instance of the implementation class and
publishes that instance in the OSGi service registry under the interface when the bundle is started.</p>
</div>
<div class="paragraph">
<p>To consume a service, an <code>&lt;osgi:reference&gt;</code> tag is used and the
service may be passed into other Spring beans using Spring&#8217;s dependency
injection facilities.</p>
</div>
<div class="paragraph">
<p>Spring DM automatically creates proxies for OSGi services so that the actual service
object may come and go at runtime.
If a service disappears, any proxies to the service will wait for the service to re-appear.
This effect is known as <strong>damping</strong>.</p>
</div>
<div class="paragraph">
<p>When a bundle is started, Spring DM builds the application contexts
specified by the XML descriptions, creates proxies for the specified services, and publishes
the specified services to the OSGi service registry.</p>
</div>
<div class="paragraph">
<p>When a bundle is stopped, Spring DM retracts any services it published on behalf of the bundle
and closes the bundle&#8217;s application contexts.
Virgo turns off damping of a service proxy while the proxy&#8217;s application context
is being closed.</p>
</div>
<div class="paragraph">
<p>Spring DM was contributed to Eclipse as the <strong>Gemini Blueprint</strong> project.
Virgo has Gemini Blueprint built-in.</p>
</div>
<div class="paragraph">
<p>Gemini Blueprint supports both Spring DM and Blueprint programming models.
Blueprint, known formally as the "OSGi Blueprint Container", provides some of the basic facilities of Spring DM,
including all those just mentioned, but in an OSGi standard form.
See <a href="#furtherreading">[furtherreading]</a> for the Blueprint specification.</p>
</div>
<div class="paragraph">
<p><a id="concepts.virgo"></a></p>
</div>
</div>
<div class="sect2">
<h3 id="_virgo_concepts">Virgo Concepts</h3>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
<div class="paragraph">
<p>This section is not relevant for Virgo Nano.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p><a id="concepts.repositories"></a></p>
</div>
<div class="sect3">
<h4 id="_the_provisioning_repository">The Provisioning Repository</h4>
<div class="paragraph">
<p>The Virgo provisioning repository contains artifacts and metadata indexed by the artifact type, name, and version. There are three kinds of repository: <strong>external</strong>, <strong>watched</strong>, and <strong>remote</strong>. Repositories are passive in the sense that changes to repository content do not cause artifacts to be deployed into Virgo, refreshed, or undeployed.</p>
</div>
</div>
<div class="sect3">
<h4 id="_artifact_types">Artifact Types</h4>
<div class="paragraph">
<p>In addition to the standard OSGi bundle, artifact types in Virgo include configuration (properties file), PAR, plan, and library.
PARs, plans, and libraries are discussed in <a href="#concepts.grouping">Grouping Bundles</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_external_repositories">External Repositories</h4>
<div class="paragraph">
<p>External repositories are created by scanning a directory which contains artifacts, possibly in nested directories. The repository configuration specifies a pattern which
says which files should be treated as artifacts. After the repository is created, changes to the directory do not affect the repository content.</p>
</div>
<div class="paragraph">
<p>Virgo&#8217;s default repository configuration, in <code>configuration/org.eclipse.virgo.repository.properties</code>, specifies an external repository created from the
<code>repository/ext</code> directory.</p>
</div>
</div>
<div class="sect3">
<h4 id="_watched_repositories">Watched Repositories</h4>
<div class="paragraph">
<p>Watched repositories are created by scanning a directory which contains artifacts but no nested directories. All files in the directory are treated as artifacts.
The directory is re-scanned periodically and the interval between re-scans is specified in the repository configuration.
The directory is also re-scanned when an artifact is deployed into Virgo.
Changes detected by re-scanning are reflected in the repository content. Note that changing the content of a watched repository does not cause artifacts to be deployed
into Virgo, refreshed, or undeployed.</p>
</div>
<div class="paragraph">
<p>Virgo&#8217;s default repository configuration specifies a watched repository based on the contents of the <code>repository/usr</code> directory.</p>
</div>
<div class="sect4">
<h5 id="_remote_repositories">Remote Repositories</h5>
<div class="paragraph">
<p>A remote repository refers to a repository hosted by a Virgo instance sometimes known as a <strong>repository server</strong>.
The hosted repository is configured using the file <code>configuration/org.eclipse.virgo.apps.repository.properties</code> and may be either an external or a watched
repository.</p>
</div>
<div class="paragraph">
<p>The remote repository is accessed by a Virgo instance sometimes known as a <strong>repository client</strong>.
The repository client is normally a different instance of Virgo to the instance hosting the repository, but it can be the same instance (which is handy for
testing). The remote repository periodically downloads its index from the hosted repository. The period between downloads may be configured in the repository
configuration. The remote repository also caches artifacts which have secure hashes associated with them in the hosted repository. Only bundles currently have secure
hashes associated with them. The secure hash is used to determine when a cached artifact is stale and needs to be freshly downloaded.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_repository_chains">Repository Chains</h4>
<div class="paragraph">
<p>The Virgo repository is configured as a <strong>chain</strong> of external, watched, and remote repositories.
The chain is a list which is searched in the configured order.
The effect of this search order is that an artifact with a given type, name, and version which appears in more than one repository in the chain is only accessed from the
first repository in the chain in which it appears. Abstractly, the repository chain behaves as a single repository, but its content may mutate in quite a different way to
the content of an individual external, watched, or remote repository.</p>
</div>
<div class="paragraph">
<p><a id="concepts.grouping"></a></p>
</div>
</div>
<div class="sect3">
<h4 id="_grouping_bundles">Grouping Bundles</h4>
<div class="paragraph">
<p>Virgo provides a way of grouping together a collection
of OSGi bundles and other artifacts which comprise a single application.
These artifacts are placed in a JAR file with extension &#8220;.par&#8221;. This is called a PAR file.</p>
</div>
<div class="paragraph">
<p>All the bundles in a PAR file are resolved together and so mutual dependencies are permitted.</p>
</div>
<div class="paragraph">
<p>At runtime a PAR file provides a <strong>scope</strong> in the sense that bundles
inside the PAR file may depend on packages and services outside the PAR file,
but bundles outside the PAR file may not depend on packages and services
provided by the PAR file.</p>
</div>
<div class="paragraph">
<p>Virgo also provides the plan artifact as another way of grouping bundles and other artifacts into an application.
A <strong>plan</strong> is a file (in XML format) listing a collection of artifacts.
The artifacts referred to by a plan reside in the Virgo provisioning repository.</p>
</div>
<div class="paragraph">
<p>In addition to PARs and plans, which are used for deploying groups of artifacts, Virgo provides libraries as a way of grouping together a collection
of bundles that can then be imported into an application using the Virgo-specific <code>Import-Library</code> manifes header.</p>
</div>
<div class="paragraph">
<p><a id="kernel.user.region"></a></p>
</div>
</div>
<div class="sect3">
<h4 id="_kernel_and_user_region">Kernel and User Region</h4>
<div class="paragraph">
<p>Conceptually, VTS can be divided into two separate subsystems, one of which actually encompases the other:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The <strong>kernel</strong>, which is the heart of VTS. It makes up most of VTS, except for the part that supports Web applications. In other words, the kernel provides full OSGi modular support for your applications, as long as they are not Web-based.
See <a href="#kernel-overview">The Virgo Kernel</a> for additional information.</p>
</li>
<li>
<p>The <strong>user region</strong> is the subsystem that manages user applications. It deliberately isolates the kernel from both your applications and those of the VTS itself, such as the Admin Console, which protects the kernel from interference by applications.
See <a href="#user-region-overview">The User Region</a> for additional information.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>When you download and install Virgo for Apache Tomcat you get both the kernel and web server support (configured in the user region). You can also <a href="http://www.eclipse.org/virgo/download/">download and use the kernel</a> on its own if you do not plan on deploying Web applications or using the
web-based Admin Console and you&#8217;ll get the kernel and a minimal user region (with no web support).</p>
</div>
<div class="paragraph">
<p>The following graphic shows how the kernel and user region make up VTS:</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="assets/images/kernel-user-region.png" alt="kernel user region"></span></p>
</div>
<div class="paragraph">
<p><a id="kernel-overview"></a></p>
</div>
</div>
<div class="sect3">
<h4 id="_the_virgo_kernel">The Virgo Kernel</h4>
<div class="paragraph">
<p>The Virgo Kernel encapsulates almost all of VTS except for the deployment of Web applications. In sum, the kernel provides the following VTS features:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Deployment of non-Web artifacts, such as OSGi bundles, PARs, plans,
and configuration artifacts.</p>
</li>
<li>
<p>Local and hosted repositories</p>
</li>
<li>
<p>Scoping</p>
</li>
<li>
<p>Hot deployment</p>
</li>
<li>
<p>User region</p>
</li>
<li>
<p>Auto-provisioning</p>
</li>
<li>
<p>System and application tracing and dump support</p>
</li>
<li>
<p>Spring beans and Blueprint support</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>See <a href="#configuring">Configuring VTS</a> for details about configuring the kernel to better suit your environment.</p>
</div>
<div class="paragraph">
<p><a id="user-region-overview"></a></p>
</div>
</div>
<div class="sect3">
<h4 id="_the_user_region">The User Region</h4>
<div class="paragraph">
<p>The user region isolates the kernel from deployed applications,
including both your own user applications and the user-oriented
VTS applications such as the Admin Console. This means
that the kernel is mostly invisible to applications and to application
management. This is because most of the kernel bundles are not
installed in the user region (apart from a few needed for region
management). The necessary function to support the kernel runs in the
OSGi framework, but the user region applications cannot see it, except
for the services that are normally offered.</p>
</div>
<div class="paragraph">
<p>This isolation has many benefits. For example, it is not necessary for the kernel and user applications to use the same version of the Spring Framework. In fact the kernel installs only those parts of the Spring Framework that it needs. If you update the kernel, it is far less likely that you will also need to upgrade or adjust the applications to accomodate a new version of the kernel. The kernel implementation is therefore much more stable and resilient and applications are much more likely to survive kernel upgrades between releases.
When you install VTS, the kernel creates a single user region.
The kernel and the user region are configured independently of each other; see <a href="#configuring">Configuring VTS</a> for details.</p>
</div>
<div class="paragraph">
<p>Finally, the isolation provided by the user region together with scoped applications and plans solve common dependency problems that occur when using OSGi.</p>
</div>
<div class="paragraph">
<p><a id="concepts.p2"></a></p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_p2_concepts">p2 Concepts</h3>
<div class="paragraph">
<p>At EclipseCon 2011 there was a great introductory presentation on p2. It gives a nice overview of the whole provisioning system.
You can find it recorded <a href="http://fosslc.org/drupal/content/gentle-introduction-p2">here(video).</a></p>
</div>
<div class="paragraph">
<p><a href="http://bkapukaranov.wordpress.com/2011/07/12/rt-meets-p2/">This blog post</a>
provides some background on why p2 was created as well as a brief overview of what p2 repositories
are and how this relates to a runtime.</p>
</div>
<div class="paragraph">
<p>This <a href="http://www.slideshare.net/PascalRapicault/understanding-and-extending-p2-for-fun-and-profit">presentation(slides only)</a>
sheds light on more advanced p2 features and turns our attention to its extension points.</p>
</div>
<div class="paragraph">
<p>Finally, the <a href="http://wiki.eclipse.org/Equinox/p2">p2 wiki</a>
also provides both getting started guides as well as information on more advanced features.</p>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2017-02-08 16:40:17 +01:00
</div>
</div>
</body>
</html>