| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="generator" content="Asciidoctor 2.0.15"> |
| <link rel="icon" type="image/png" href="/favicon.png"> |
| <title>Eclipse CommaSuite</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 | https://asciidoctor.org */ |
| /* Uncomment @import statement to use as 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{display:block} |
| audio,video{display:inline-block} |
| audio:not([controls]){display:none;height:0} |
| html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%} |
| a{background:none} |
| 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} |
| 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;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased} |
| 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} |
| img,object,svg{display:inline-block;vertical-align:middle} |
| textarea{height:auto;min-height:50px} |
| select{width:100%} |
| .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} |
| a{color:#2156a5;text-decoration:underline;line-height:inherit} |
| a:hover,a:focus{color:#1d4b8f} |
| a img{border:0} |
| 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 #dddddf;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{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} |
| 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,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)} |
| @media 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;word-wrap:normal} |
| table thead,table tfoot{background:#f7f8f7} |
| 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{background:#f8f8f7} |
| table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6} |
| 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} |
| .center{margin-left:auto;margin-right:auto} |
| .stretch{width:100%} |
| .clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table} |
| .clearfix::after,.float-group::after{clear:both} |
| :not(pre).nobreak{word-wrap:normal} |
| :not(pre).nowrap{white-space:nowrap} |
| :not(pre).pre-wrap{white-space:pre-wrap} |
| :not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed} |
| pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed} |
| pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit} |
| pre>code{display:block} |
| pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal} |
| em em{font-style:normal} |
| strong strong{font-weight:400} |
| .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:#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,.menuref{color:#000} |
| .menuseq b:not(.caret),.menuref{font-weight:inherit} |
| .menuseq{word-spacing:-.02em} |
| .menuseq b.caret{font-size:1.25em;line-height:.8} |
| .menuseq i.caret{font-weight:bold;text-align:center;width:.45em} |
| 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 #dddddf} |
| #header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px} |
| #header .details{border-bottom:1px solid #dddddf;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 #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem} |
| #toc{border-bottom:1px solid #e7e7e9;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 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:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;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 #e7e7e9;left:auto;right:0}} |
| @media 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:none;background:rgba(0,0,0,.8);padding:1.25em} |
| #footer-text{color:rgba(255,255,255,.8);line-height:1.44} |
| #content{margin-bottom:.625em} |
| .sect1{padding-bottom:.625em} |
| @media screen and (min-width:768px){#content{margin-bottom:1.25em} |
| .sect1{padding-bottom:1.25em}} |
| .sect1:last-child{padding-bottom:0} |
| .sect1+.sect1{border-top:1px solid #e7e7e9} |
| #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} |
| details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em} |
| details>summary:first-of-type{cursor:pointer;display:list-item;outline:none;margin-bottom:.75em} |
| .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.fit-content>caption.title{white-space:nowrap;width:0} |
| .paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)} |
| table.tableblock #preamble>.sectionbody>[class="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 #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere} |
| .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:#dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;-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>.content>pre{-webkit-border-radius:4px;border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em} |
| @media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}} |
| @media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}} |
| .literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class="highlight"],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8} |
| .literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)} |
| .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:inherit;opacity:.5} |
| .listingblock:hover code[data-lang]::before{display:block} |
| .listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5} |
| .listingblock.terminal pre .command:not([data-prompt])::before{content:"$"} |
| .listingblock pre.highlightjs{padding:0} |
| .listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px} |
| .listingblock pre.prettyprint{border-width:0} |
| .prettyprint{background:#f7f7f8} |
| pre.prettyprint .linenums{line-height:1.45;margin-left:2em} |
| pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0} |
| pre.prettyprint li code[data-lang]::before{opacity:1} |
| pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none} |
| table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none} |
| table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal} |
| table.linenotable td.code{padding-left:.75em} |
| table.linenotable td.linenos{border-right:1px solid currentColor;opacity:.35;padding-right:.5em} |
| pre.pygments .lineno{border-right:1px solid currentColor;opacity:.35;display:inline-block;margin-right:.75em} |
| pre.pygments .lineno::before{content:"";margin-right:-.125em} |
| .quoteblock{margin:0 1em 1.25em 1.5em;display:table} |
| .quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em} |
| .quoteblock blockquote,.quoteblock 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:.75em;margin-right:.5ex;text-align:right} |
| .verseblock{margin:0 1em 1.25em} |
| .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 blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none} |
| .quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0} |
| .quoteblock.abstract{margin:0 1em 1.25em;display:block} |
| .quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center} |
| .quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf} |
| .quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0} |
| .quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem} |
| .quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0} |
| p.tableblock:last-child{margin-bottom:0} |
| td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere} |
| td.tableblock>.content>:last-child{margin-bottom:-1.25em} |
| table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede} |
| table.grid-all>*>tr>*{border-width:1px} |
| table.grid-cols>*>tr>*{border-width:0 1px} |
| table.grid-rows>*>tr>*{border-width:1px 0} |
| table.frame-all{border-width:1px} |
| table.frame-ends{border-width:1px 0} |
| table.frame-sides{border-width:0 1px} |
| table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0} |
| table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0} |
| table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0} |
| table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0} |
| table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd),table.stripes-even tr:nth-of-type(even),table.stripes-hover tr:hover{background:#f8f8f7} |
| 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{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} |
| 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.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none} |
| ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em} |
| ul.unstyled,ol.unstyled{margin-left:0} |
| 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:1.25em;font-size:.8em;position:relative;bottom:.125em} |
| ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em} |
| ul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em} |
| ul.inline>li{margin-left:1.25em} |
| .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} |
| td.hdlist2{word-wrap:anywhere} |
| .literalblock+.colist,.listingblock+.colist{margin-top:-.5em} |
| .colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top} |
| .colist td:not([class]):first-child img{max-width:none} |
| .colist td:not([class]):last-child{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{margin:.25em .625em 1.25em 0} |
| .imageblock.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;border-width:1px 0 0} |
| #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em} |
| #footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em} |
| #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:#00fafa} |
| .black{color:#000} |
| .black-background{background:#000} |
| .blue{color:#0000bf} |
| .blue-background{background:#0000fa} |
| .fuchsia{color:#bf00bf} |
| .fuchsia-background{background:#fa00fa} |
| .gray{color:#606060} |
| .gray-background{background:#7d7d7d} |
| .green{color:#006000} |
| .green-background{background:#007d00} |
| .lime{color:#00bf00} |
| .lime-background{background:#00fa00} |
| .maroon{color:#600000} |
| .maroon-background{background:#7d0000} |
| .navy{color:#000060} |
| .navy-background{background:#00007d} |
| .olive{color:#606000} |
| .olive-background{background:#7d7d00} |
| .purple{color:#600060} |
| .purple-background{background:#7d007d} |
| .red{color:#bf0000} |
| .red-background{background:#fa0000} |
| .silver{color:#909090} |
| .silver-background{background:#bcbcbc} |
| .teal{color:#006060} |
| .teal-background{background:#007d7d} |
| .white{color:#bfbfbf} |
| .white-background{background:#fafafa} |
| .yellow{color:#bfbf00} |
| .yellow-background{background:#fafa00} |
| span.icon>.fa{cursor:default} |
| a span.icon>.fa{cursor:inherit} |
| .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:rgba(0,0,0,.8);-webkit-border-radius:50%;border-radius:50%;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:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc} |
| .print-only{display:none!important} |
| @page{margin:1.25cm .75cm} |
| @media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important} |
| html{font-size:80%} |
| 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} |
| #header,#content,#footnotes,#footer{max-width:none} |
| #toc,.sidebarblock,.exampleblock>.content{background:none!important} |
| #toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important} |
| body.book #header{text-align:center} |
| body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em} |
| 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{padding:0 .9375em} |
| .hide-on-print{display:none!important} |
| .print-only{display:block!important} |
| .hide-for-print{display:none!important} |
| .show-for-print{display:inherit!important}} |
| @media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem} |
| .sect1{padding:0!important} |
| .sect1+.sect1{border:0} |
| #footer{background:none} |
| #footer-text{color:rgba(0,0,0,.6);font-size:.9em}} |
| @media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}} |
| </style> |
| <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"> |
| </head> |
| <body class="article toc2 toc-left"> |
| <div id="header"> |
| <div id="toc" class="toc2"> |
| <div id="toctitle">Index</div> |
| <ul class="sectlevel1"><li><a style="" href="../index.html">Home</a></li><li><a style="" href="../site/download.html">Download</a></li><li><a style="" href="../site/developers.html">Developers</a></li><li><a style="" href="../user_guide.html">User guide</a><ul class="sectlevel2"><li><a style="" href="../overview/intro.html">Language overview</a><ul class="sectlevel3"><li><a style="" href="../overview/gettingstarted.html">Getting started</a><ul class="sectlevel4"></ul></li><li><a style="" href="../language/language.html">Language</a><ul class="sectlevel4"><li><a style="" href="../language/types.html">Types</a><ul class="sectlevel5"></ul></li><li><a style="" href="../language/interfaces.html">Interface signatures</a><ul class="sectlevel5"></ul></li><li><a style="" href="../language/statemachines.html">Interfaces</a><ul class="sectlevel5"><li><a style="" href="../language/states.html">States</a><ul class="sectlevel6"></ul></li><li><a style="" href="../language/transitions.html">Transitions</a><ul class="sectlevel6"></ul></li><li><a style="" href="../language/timing_constraints.html">Timing constraints</a><ul class="sectlevel6"></ul></li><li><a style="" href="../language/data_constraints.html">Data constraints</a><ul class="sectlevel6"></ul></li><li><a style="" href="../language/generic_constraints.html">Generic constraints</a><ul class="sectlevel6"></ul></li></ul></li><li><a style="" href="../language/components.html">Components</a><ul class="sectlevel5"></ul></li><li><a style="" href="../language/expressions.html">Statements and expressions</a><ul class="sectlevel5"></ul></li><li><a style="" href="../language/comments.html">Documenting models</a><ul class="sectlevel5"></ul></li></ul></li></ul></li><li><a style="" href="generators.html">Generator tasks</a><ul class="sectlevel3"><li><a style="" href="umlgeneration.html">Generation of UML diagrams</a><ul class="sectlevel4"></ul></li><li><a style="" href="docgeneration.html">Document generation</a><ul class="sectlevel4"></ul></li><li><a style="font-weight: bold" href="monitoring.html">Monitoring</a><ul class="sectlevel4"></ul></li><li><a style="" href="reachabilitygraph.html">Reachability graph</a><ul class="sectlevel4"></ul></li><li><a style="" href="testgeneration.html">Test generation</a><ul class="sectlevel4"></ul></li></ul></li><li><a style="" href="../tutorial/intro.html">Tutorial</a><ul class="sectlevel3"><li><a style="" href="../tutorial/preparation.html">Preparation</a><ul class="sectlevel4"></ul></li><li><a style="" href="../tutorial/serviceinterface.html">Service interface</a><ul class="sectlevel4"><li><a style="" href="../tutorial/activity1.html">Activity 1: Get familiar with the Vending Machine</a><ul class="sectlevel5"></ul></li><li><a style="" href="../tutorial/activity2.html">Activity 2: Make an initial specification of the service interface</a><ul class="sectlevel5"></ul></li><li><a style="" href="../tutorial/activity3.html">Activity 3: Check an execution trace against the state machine</a><ul class="sectlevel5"></ul></li><li><a style="" href="../tutorial/activity4.html">Activity 4: Extend the specification of the service interface</a><ul class="sectlevel5"></ul></li><li><a style="" href="../tutorial/activity5.html">Activity 5: Add a time constraint</a><ul class="sectlevel5"></ul></li><li><a style="" href="../tutorial/activity6.html">Activity 6: Documentation generation</a><ul class="sectlevel5"></ul></li></ul></li><li><a style="" href="../tutorial/coincheckinterface.html">Coin checker interface</a><ul class="sectlevel4"><li><a style="" href="../tutorial/activity7.html">Activity 7: State machine of the coin checker</a><ul class="sectlevel5"></ul></li><li><a style="" href="../tutorial/activity8.html">Activity 8: Check the specified interfaces by monitoring</a><ul class="sectlevel5"></ul></li></ul></li><li><a style="" href="../tutorial/userinterface.html">User interface</a><ul class="sectlevel4"><li><a style="" href="../tutorial/activity9.html">Activity 9: State machine of the user interface</a><ul class="sectlevel5"></ul></li><li><a style="" href="../tutorial/activity10.html">Activity 10: Check the specified interfaces by monitoring</a><ul class="sectlevel5"></ul></li><li><a style="" href="../tutorial/activity11.html">Activity 11: Define time constraints</a><ul class="sectlevel5"></ul></li><li><a style="" href="../tutorial/activity12.html">Activity 12: Define a data constraint</a><ul class="sectlevel5"></ul></li></ul></li><li><a style="" href="../tutorial/componentmodel.html">Component model</a><ul class="sectlevel4"><li><a style="" href="../tutorial/activity13.html">Activity 13: Define component and add functional constraint</a><ul class="sectlevel5"></ul></li><li><a style="" href="../tutorial/activity14.html">Activity 14: Define additional component constraints</a><ul class="sectlevel5"></ul></li></ul></li><li><a style="" href="../tutorial/concludingremarks.html">Concluding remarks</a><ul class="sectlevel4"></ul></li></ul></li><li><a style="" href="../commandline/commandline.html">Command line tool</a><ul class="sectlevel3"></ul></li><li><a style="" href="../eventfiles/eventfiles.html">Event files</a><ul class="sectlevel3"></ul></li><li><a style="" href="../shortcuts/shortcuts.html">Shortcuts</a><ul class="sectlevel3"></ul></li><li><a style="" href="../problems/problemsolving.html">Problem solving</a><ul class="sectlevel3"></ul></li></ul></li></ul> |
| </div> |
| </div> |
| <div id="content"> |
| <div class="sect1"> |
| <h2 id="_monitoring"><a class="anchor" href="#_monitoring"></a>Monitoring</h2> |
| <div class="sectionbody"> |
| <div class="paragraph normal"> |
| <p>Monitoring is a process of checking if the observed behavior of a component conforms to a behavioral specification. Behavioral specifications can be interface models and component models. In case of interface model the process is interface monitoring: a check if the behavior of a component that provides the interface conforms to the interface definition. In case of component model the process is component monitoring: a check if the behavior of a component conforms to the functional, time and data constraints in the model.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To perform monitoring with the CommaSuite framework, the following ingredients are required:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Behavioral model (.interface or .component file). The model in turn imports interface and signature definitions.</p> |
| </li> |
| <li> |
| <p>One or more trace files with events (calls to commands and signals, notifications and replies to commands) observed during a component execution. Traces are stored in files with extension .events. It is not recommended to create such files manually. They are usually obtained via network sniffing or from execution logs. Trace file names have to start with a letter and have to contain only letters, digits and underscore ("_").</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>In order to perform monitoring, follow the steps:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Include one or more tasks for monitor generation in the CommaSuite project file. A monitoring task has to specify how the trace files are obtained. Trace files can be listed, a folder with trace files can be given, or they can be produced by another generation task. Furthermore, the task has to indicate the behavioral model (interface or component). In the example below a single file with traces is used (TraceITest.events) for interface monitoring:</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Generate Monitors { |
| iTestMonitor for interface ITest { |
| trace files |
| "TraceITest.events" |
| } |
| }</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following example shows a task that uses a directory (named trace_files) with traces for component monitoring:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Generate Monitors { |
| monitorTask for component Imaging { |
| trace directories |
| "trace_files" |
| } |
| }</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If the trace files are produced by another task then refer to the task:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Generate Monitors { |
| iTestMonitor for interface ITest { |
| trace files |
| task traceProducer |
| } |
| }</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Trace directories have to contain trace files with unique names. If two directories contain distinct files with the same name an error will be indicated.</p> |
| </div> |
| <div class="paragraph"> |
| <p>During monitoring all time and data constraints defined in the interface or component are checked over the traces. In some cases users may need to skip the check of time and data constraints due to various reasons, for example when the real hardware is not present yet thus making the execution environment different than the expected one. Constraint checks can be skipped by including one of the instructions <em>skip time constraints, skip data constraints, skip constraints</em>. The following example monitoring task skips both time and data constraints:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Generate Monitors { |
| iTestMonitor for interface ITest { |
| skip constraints |
| |
| trace files |
| task traceProducer |
| } |
| }</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In case of component monitoring, interface monitoring is performed as well for the interfaces on each component port. Every event used in a component instance is first checked by the corresponding interface monitor and after that passed to the component monitor. The component monitor checks if functional, data and time constraints are satisfied.</p> |
| </div> |
| </li> |
| <li> |
| <p>Generate the monitoring code and execute it. After a right mouse button click on the project file, select 'Run As'. Select the first item: "CommaSuite Generation and Monitoring". As a result, all generator tasks will be executed followed by execution of all the monitoring tasks. Results are located in the folder "comma-gen" (explained further on this page).</p> |
| </li> |
| </ol> |
| </div> |
| <div class="sect2"> |
| <h3 id="_inspecting_the_results_of_monitoring"><a class="anchor" href="#_inspecting_the_results_of_monitoring"></a>Inspecting the Results of Monitoring</h3> |
| <div class="paragraph"> |
| <p>Monitoring results unite the results from all traces in all monitoring tasks in the given project file.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For a given trace:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>in case of interface monitoring, all connections in the trace over the given interface are monitored</p> |
| </li> |
| <li> |
| <p>in case of component monitoring, all instances of the given component model are monitored</p> |
| </li> |
| <li> |
| <p>if trace error occurs (this is a syntax error in the events file) all monitoring stops and the results obtained so far are reported along with the trace error</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For interface monitoring, we may observe:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>interface error: a violation of the behavior given in interface state machines. Monitoring of the corresponding connection stops</p> |
| </li> |
| <li> |
| <p>interface warning: a violation of interface time/data/generic constraints. Monitoring of the connection continues</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For component monitoring, we may observe:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>component error: a violation of a functional component constraint. Monitoring of this constraint stops</p> |
| </li> |
| <li> |
| <p>component warning: a violation of a component time/data/generic constraint. Monitoring of the component instance continues</p> |
| </li> |
| <li> |
| <p>port error: interface error in a connection to a component port. Monitoring of functional and time/data constraints for the corresponding instance stops. |
| Interface monitoring of the remaining port connections continues</p> |
| </li> |
| <li> |
| <p>port warning: interface warning in a connection to a component port. Monitoring of the component instance continues</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>In order to inspect the monitoring results:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Navigate to folder <em>comma-gen</em>. For every monitoring task, a folder with the name of the task is created. A summary of the results from all tasks is stored in JSON format in file <em>tasksResults.json</em>. Furthermore, a web page <em>dashboard.html</em> is automatically created. It contains an overview of the results per trace. If you want more detailed information about the results continue to step 2. Every task results folder has the following structure:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>One folder for each trace file, named after the file name</p> |
| </li> |
| <li> |
| <p>Folder <em>statistics</em> that contains information about the checking of the time and data constraints (if any) |
| <br> |
| <span class="image"><img src="../img/executionResult.jpg" alt="image"></span></p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Inspect the results for a particular trace file by opening the corresponding folder. Results are structured differently for interface and component monitoring.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>Interface monitoring</em>. |
| For every connection |
| (usage of an interface by a unique pair of client and server) |
| there will be a folder with name $ServerName$_$ClientName$_$Interface$. |
| The folder has at least two files: $ServerName$_$ClientName$_$Interface$_trace.txt that contains the processed trace and $ServerName$_$ClientName$_$Interface$_results.txt that contains a summary of the monitoring results for the connection. |
| If errors and warnings are detected they will result in additional files.</p> |
| <div class="paragraph"> |
| <p><span class="image"><img src="../img/error.jpg" alt="image"></span><br> |
| In case of detected issues, they are described by giving the context and their exact nature. Errors and warnings are also described in separate files that can be visualized in the PlantUML view.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Visualize the content of .plantuml files (if any) in the PlantUML view to check the description of the error/warning. |
| The issue is reported in a UML sequence diagram that gives the path to the error and a description.<br> |
| <span class="image"><img src="../img/errorPlantUML.png" alt="image"></span><br></p> |
| </div> |
| </li> |
| <li> |
| <p><em>Component monitoring</em>. |
| For every component instance in the given trace file there will be a folder named after the component instance. |
| Each such folder further contains one folder per component port (named after the port), one folder per functional constraint (named after the constraint), and one folder named <em>time_data</em> that contains the results of checking the time and data constraints in the component model (if any). |
| The folders derived from the ports contain the results of the interface monitoring on the given port. |
| The results in all the folders are structured similarly to the case of interface monitoring: one text file with a summary of the results, one text file with the processed trace (up to the occurrence of an error if any), and possibly many files with error/warning descriptions.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_interface_monitoring_and_non_determinism"><a class="anchor" href="#_interface_monitoring_and_non_determinism"></a>Interface Monitoring and Non-Determinism</h3> |
| <div class="paragraph"> |
| <p>Interface specifications support non-determinism by allowing multiple ways to react to a given trigger (check the interface language and the "OR" clause in particular). The presence of non-determinism affects how monitoring is performed and how monitoring results are reported.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In general, when a non-determinism is detected during monitoring, the monitor will maintain and explore all execution paths. As more events from the trace are checked by the monitor, some execution paths may be identified as erroneous and therefore discarded. If all paths at a given moment do not allow the occurrence of an event then a monitoring error is reported and contextual information for all the paths will be shown.</p> |
| </div> |
| <div class="paragraph"> |
| <p>We give an example of monitoring error in case of non-determinism and explain the structure of the reported results.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Imagine the interface of a simple vending machine that accepts coins and delivers products on user request. When a coin is inserted, the machine checks first if this is a valid coin and then reports the outcome to the user together with the value of possibly updated credit. If the machine is in error state then the coin is simply returned. The code snippet shows only the transition when a coin is inserted:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>initial state NoCredit { |
| transition trigger: InsertCoin(int val) |
| do: credit := credit + 1 |
| reply(credit,CoinResult::ACCEPTED) |
| next state: CreditAvailable |
| OR |
| do: |
| reply(credit,CoinResult::NOT_ACCEPTED) |
| next state: NoCredit |
| OR |
| do: |
| reply(0,CoinResult::NOT_OPERATIONAL) |
| next state: NoCredit |
| .... |
| }</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>After inserting the coin, the transition gives three possible paths. This is an example of non-determinism. By reading the observed reply in the trace, the monitoring algorithm can determine which path to take or possibly an error is detected. Consider the following trace:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Command InsertCoin |
| Reply to command InsertCoin. Parameters: -1 CoinResult::NOT_OPERATIONAL</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The trace will cause an error because the reply parameters do not match any of the expected values given in the three possible transition bodies. All the three possible executions at the moment of observing the reply will be reported in the monitoring results.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The text file with the results will contain the following:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Interface monitoring error |
| The event does not conform to the model |
| |
| Possible events in the current state of the model: |
| |
| Reply to command InsertCoin. Parameters: 1 CoinResult::ACCEPTED |
| Reply to command InsertCoin. Parameters: 0 CoinResult::NOT_ACCEPTED |
| Reply to command InsertCoin. Parameters: 0 CoinResult::NOT_OPERATIONAL |
| |
| Execution states of the model: |
| |
| Active state: NoCredit |
| Values of global variables and current machine states: |
| |
| credit = 0 |
| Machine userMachine in state NoCredit |
| |
| Active state: NoCredit |
| Values of global variables and current machine states: |
| |
| credit = 0 |
| Machine userMachine in state NoCredit |
| |
| Active state: NoCredit |
| Values of global variables and current machine states: |
| |
| credit = 0 |
| Machine userMachine in state NoCredit</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>As can be seen there is a description for each possible execution. It contains: the state in which the event is observed (active state), the values of interface variables, the current states of the interface state machines (recall that multiple machines are possible). In our example, it happens that all executions have the same information.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The visualization of the error as a sequence diagram will contain similar information:</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="../img/MonitorErrorAndNonDeterminism.png" alt="image"></span></p> |
| </div> |
| <div class="paragraph"> |
| <p>The three sections in the note indicate the three possible executions at the moment of observing the reply. In this example they are identical.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_singleton_and_multiton_interface_monitoring"><a class="anchor" href="#_singleton_and_multiton_interface_monitoring"></a><span id="singleton_multiton_monitoring">Singleton and Multiton Interface Monitoring</span></h3> |
| <div class="paragraph"> |
| <p>The singleton/multiton distinction of an interface determines how the interface is monitored. Generally, a trace file contains information about servers that provide interfaces and clients that use them. A single server may have multiple clients of a given interface. A triplet of a client that uses an interface provided by a server is called <em>connection</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A multiton interface is monitored by creating a separate monitor for every connection over that interface.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A singleton interface is monitored by creating a single monitor for all the connections that have the same server at their end. This reflects the fact that the clients of a singleton interface share one instance. In other words, the monitor of a singleton interface does not distinguish its clients, it treats them as a single client.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </body> |
| </html> |
