You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by bu...@apache.org on 2014/02/10 22:28:27 UTC
svn commit: r897213 [33/33] - in /websites/staging/isis/trunk: cgi-bin/
content/ content/applib-guide/ content/archetypes/
content/archetypes/release-notes/ content/components/objectstores/jdo/
content/components/security/shiro/ content/core/ content/c...
Added: websites/staging/isis/trunk/content/reference/services/xmlsnapshot-service.html
==============================================================================
--- websites/staging/isis/trunk/content/reference/services/xmlsnapshot-service.html (added)
+++ websites/staging/isis/trunk/content/reference/services/xmlsnapshot-service.html Mon Feb 10 21:28:21 2014
@@ -0,0 +1,475 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+
+ <meta charset="utf-8">
+ <title>XML Snapshot Service [1.4.0-SNAPSHOT]</title>
+ <meta name="description" content="">
+ <meta name="author" content="">
+
+ <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
+ <!--[if lt IE 9]>
+ <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
+ <![endif]-->
+
+
+ <!-- Le styles -->
+ <link href="./../../bootstrap-3.0.0/css/bootstrap.css" rel="stylesheet">
+ <link href="./../../prettify.css" rel="stylesheet">
+
+ <style type="text/css">
+ body {
+ padding-top: 60px;
+ }
+ .sprite {
+ display: inline-block;
+ height: 20px;
+ margin: 0 auto 4px;
+ outline: medium none;
+ text-indent: -999em;
+ width: 24px;
+ background-image: url('./../../images/sprites.png');
+ background-repeat: no-repeat;
+ overflow: hidden;
+ cursor: pointer;
+ }
+ .edit-page {
+ display: inline-block;
+ height: 20px;
+ margin: 0 auto 4px;
+ outline: medium none;
+ text-indent: -999em;
+ width: 24px;
+ background-image: url('./../../images/edit.png');
+ background-repeat: no-repeat;
+ overflow: hidden;
+ cursor: pointer;
+ }
+ .fb-share {
+ background-position: 0px -40px;
+ }
+ .gp-share {
+ background-position: 0px 0px;
+ }
+ .tw-share {
+ background-position: 0px -80px;
+ }
+ .markdown-content {
+ min-height: 500px;
+ }
+ .book-image img {
+ border: 1px;
+ border-style: solid;
+ }
+ .release-matrix .heading {
+ background-color: #eeeeee;
+ }
+ .release-matrix .new {
+ color: #dd0000;
+ font-weight: bolder;
+ }
+ .stub,.note {
+ position: relative;
+ padding: 7px 15px;
+ margin-bottom: 18px;
+ color: #404040;
+ background-color: #eedc94;
+ background-repeat: repeat-x;
+ background-image: -khtml-gradient(linear, left top, left bottom, from(#fceec1), to(#eedc94));
+ background-image: -moz-linear-gradient(top, #fceec1, #eedc94);
+ background-image: -ms-linear-gradient(top, #fceec1, #eedc94);
+ background-image: -webkit-gradient(linear, left top, left bottom, color-stop(0%, #fceec1), color-stop(100%, #eedc94));
+ background-image: -webkit-linear-gradient(top, #fceec1, #eedc94);
+ background-image: -o-linear-gradient(top, #fceec1, #eedc94);
+ background-image: linear-gradient(top, #fceec1, #eedc94);
+ filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#fceec1', endColorstr='#eedc94', GradientType=0);
+ text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.25);
+ border-color: #eedc94 #eedc94 #e4c652;
+ border-color: rgba(0, 0, 0, 0.1) rgba(0, 0, 0, 0.1) rgba(0, 0, 0, 0.25);
+ text-shadow: 0 1px 0 rgba(255, 255, 255, 0.5);
+ border-width: 1px;
+ border-style: solid;
+ -webkit-border-radius: 4px;
+ -moz-border-radius: 4px;
+ border-radius: 4px;
+ -webkit-box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.25);
+ -moz-box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.25);
+ box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.25);
+ }
+
+ div.XXXisis-tweak form {
+ margin-top: 6px;
+ margin-bottom: -2px;
+ }
+
+ div.row div.col-md-12 {
+ border-top: 1px solid #eeeeee;
+ }
+
+
+ /* Isis specific stuff */
+
+ .container {
+ width: 940px;
+ }
+
+ .markdown-content .documentation .span-one-third p {
+ margin-bottom: 0px;
+ }
+
+ .markdown-content .documentation .group {
+ margin-top: 9px;
+ }
+
+ .documentation .group h2 {
+ border-bottom: 1px solid #DDD
+ }
+ .documentation h2 a, .documentation h3 a {
+ /* same as code style */
+ padding: 0 3px 2px;
+ font-family: Monaco, Andale Mono, Courier New, monospace;
+ font-size: 12px;
+ -webkit-border-radius: 3px;
+ -moz-border-radius: 3px;
+ border-radius: 3px;
+ padding: 1px 3px;
+ }
+
+ .carousel-indicators li {
+ border: 1px solid rgb(192,70,1);
+ }
+
+ .carousel-indicators li.active {
+ background-color: rgb(192,70,1);
+ }
+
+ .carousel-control .icon-prev,
+ .carousel-control .icon-next {
+ color: rgb(192,70,1);
+ font-size: 60px;
+ }
+
+ .page-header {
+ margin-top: 0px;
+ }
+
+ </style>
+ <script type="text/javascript">
+ function fbshare () {
+ window.open(
+ "http://www.facebook.com/sharer/sharer.php?u="+document.URL,
+ 'Share on Facebook',
+ 'width=640,height=426');
+ };
+ function gpshare () {
+ window.open(
+ "https://plus.google.com/share?url="+document.URL,
+ 'Share on Google+',
+ 'width=584,height=385');
+ };
+ function twshare () {
+ window.open(
+ "https://twitter.com/intent/tweet?url="+document.URL+"&text=XML Snapshot Service [1.4.0-SNAPSHOT]",
+ 'Share on Twitter',
+ 'width=800,height=526');
+ };
+ </script>
+
+ <!-- Le fav and touch icons -->
+ <link rel="shortcut icon" href="./../../images/favicon.ico">
+
+ <script src="./../../javascript/prettify.js" type="text/javascript"></script>
+
+ <script src="//code.jquery.com/jquery.js"></script>
+ <script src="./../../javascript/prettyprint.js"></script>
+ <script src="./../../bootstrap-3.0.0/js/bootstrap.js"></script>
+
+
+ <script src="http://platform.twitter.com/widgets.js" type="text/javascript"></script>
+ <!--
+ <DISABLEDscript src="./../../javascript/common.js"></DISABLEDscript>
+ -->
+
+
+
+
+
+ <script>
+ $(function () { prettyPrint() })
+ $().dropdown()
+ </script>
+
+ </head>
+
+ <body>
+
+ <nav class="navbar navbar-fixed-top navbar-inverse" role="navigation">
+ <div class="container">
+ <a class="navbar-brand" href="./../../index.html">Apache Isis™</a>
+ <ul class="nav navbar-nav">
+ <li><a href="./../../download.html">Download</a></li>
+ <li><a href="./../../documentation.html">Documentation</a></li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Screenshots<b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a href="./../../getting-started/screenshots.html">Screenshots</a></li>
+ <li><a href="./../../getting-started/screencasts.html">Screencasts</a></li>
+ <li><a href="./../../getting-started/powered-by.html">Powered by</a></li>
+ <li><a href="http://isisdemo.mmyco.co.uk/">Online Demo</a></li>
+ </ul>
+ </li>
+
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Support<b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a href="./../../support.html">Mailing Lists</a></li>
+ <li><a href="http://isis.markmail.org/search/?q=">ML Archives</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/ISIS">JIRA</a></li>
+ <li><a href="http://stackoverflow.com/questions/tagged/isis">Stack Overflow</a></li>
+ <li><a href="http://github.com/apache/isis">Github mirror</a></li>
+ </ul>
+ </li>
+
+ <FORM class="navbar-form navbar-right" id="searchbox_012614087480249044419:dn-q5gtwxya" action="http://www.google.com/cse">
+ <div class="form-group">
+ <input type="hidden" name="cx" value="012614087480249044419:dn-q5gtwxya">
+ <INPUT type="hidden" name="cof" value="FORID:0">
+ <INPUT class="form-control" name="q" type="text" placeholder="Search">
+ </div>
+ </FORM>
+
+ <li class="dropdown navbar-right">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Apache <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="http://www.apache.org/">Apache Homepage <i class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/licenses/">Licenses <i class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/security/">Security <i class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship <i class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/foundation/thanks.html">Thanks <i class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="./../../more-thanks.html">More thanks <i class="icon-share-alt"></i></a>
+ </li>
+ </ul>
+ </li>
+ </ul>
+
+ </div>
+ </nav>
+
+ <div class="container">
+ <div class="markdown-content">
+
+
+<div class="page-header">
+<p><a href="./../../documentation.html">Docs</a> » <a href="./../../reference/about.html">Reference</a> » <a href="./../../reference/services/about.html">Services</a></p>
+<h1>XML Snapshot Service [1.4.0-SNAPSHOT]
+
+</h1>
+</div>
+
+<p>The <em>Apache Isis</em> framework provides the capability to generate XML snapshots (and if required corresponding XSD schemas) based on graphs of domain objects. </p>
+
+<h3>API</h3>
+
+<pre><code>public interface XmlSnapshotService {
+
+ public interface Snapshot {
+ public Document getXmlDocument();
+ public Document getXsdDocument();
+
+ public String getXmlDocumentAsString();
+ public String getXsdDocumentAsString();
+ }
+
+ public interface Builder {
+ public void includePath(final String path);
+ public void includePathAndAnnotation(final String path, final String annotation);
+ }
+
+ public static class Exception extends RuntimeException { ... }
+
+ @Programmatic
+ public XmlSnapshotService.Snapshot snapshotFor(final Object domainObject);
+
+ @Programmatic
+ public XmlSnapshotService.Builder builderFor(final Object domainObject);
+
+ public Document asDocument(String xmlStr);
+
+ public <T> T getChildElementValue(final Element el, final String tagname, final Class<T> expectedCls);
+
+ public Element getChildElement(final Element el, final String tagname);
+
+ public String getChildTextValue(final Element el);
+}
+</code></pre>
+
+<p>where:</p>
+
+<ul>
+<li><code>asDocument()</code> is a convenience to convert xml string back into a W3C Document</li>
+<li><code>getChildElementValue()</code> is a convenience to extract the value of an XML element, based on its type.</li>
+<li><code>getChildElement()</code> is a convenience method to walk XML document.</li>
+<li><code>getChildTextValue()</code> is a convenience method to obtain value of child text node.</li>
+</ul>
+
+<h3>Usage</h3>
+
+<blockquote>
+ <p>TO DOCUMENT</p>
+</blockquote>
+
+<h3>Usage (Deprecated)</h3>
+
+<p>This is done using the
+<code>org.apache.isis.core.runtime.snapshot.XmlSnapshot</code> class.</p>
+
+<h4>Generating an XML Snapshot</h4>
+
+<p>The <code>XmlSnapshot</code> can be created either directly or using a builder.</p>
+
+<h4>Basic Usage</h4>
+
+<p>The standard usage is to instantiate directly.</p>
+
+<pre><code>XmlSnapshot snapshot = new XmlSnapshot(customer);
+Element customerAsXml = snapshot.getXmlElement();
+</code></pre>
+
+<p>This will return the Customer's fields, titles of simple references, number of items in collections.</p>
+
+<p>In order to use the <code>XmlSnapshot</code>, the domain object must implement <code>org.apache.isis.applib.snapshot.Snapshottable</code>. This is just a marker interface.</p>
+
+<h4>Including other Elements</h4>
+
+<p>It's also possible to instruct the <code>XmlSnapshot</code> to "walk" the object graph and include other information within the generated XML.</p>
+
+<p>For example:</p>
+
+<pre><code>XmlSnapshot snapshot = new XmlSnapshot(customer);
+snapshot.include("placeOfBirth"); // (1)
+snapshot.include("orders/product"); // (2)
+Element customerAsXml = snapshot.getXmlElement();
+</code></pre>
+
+<p>In (1), we indicate that we want to also navigate to another domain object represented by simple reference <code>"placeOfBirth"</code>; in (2), we indicate that we want to navigate the <code>"orders"</code> collection (presumably of <code>Order</code>s) and for each referenced <code>Order</code>, to navigate in turn its <code>"product"</code> reference (presumably to a <code>Product</code> class).</p>
+
+<p>Note that <code>XmlSnapshot</code> is mutable, in that calls to its <code>getXmlElement()</code> may return different XML structures based on whether additional paths have been <code>include()</code>d, or whether the state of the domain objects themselves have changed.</p>
+
+<h4>Using the Fluent API</h4>
+
+<p>An <code>XmlSnapshot</code> can also be constructed using an alternative "fluent" API:</p>
+
+<pre><code>XmlSnapshot snapshot =
+ XmlSnapshot.create(customer)
+ .includePath("placeOfBirth")
+ .include("orders/product")
+ .build();
+Element customerAsXml = snapshot.getXmlElement();
+</code></pre>
+
+<h4>The SnapshottableWithInclusions interface</h4>
+
+<p>As already mentioned, in order to be snapshotted a domain object must implement the <code>Snapshottable</code> interface. This is just a marker interface, so implementing it is trivial.</p>
+
+<p>Alternatively, the domain object can choose to implement the
+sub-interface, <code>SnapshottableWithInclusions</code>. This moves the
+responsibility for determining what is included within the snapshot from the caller to the snapshottable object itself:</p>
+
+<pre><code>public interface SnapshottableWithInclusions extends Snapshottable {
+ List<String> snapshotInclusions();
+}
+</code></pre>
+
+<p>If necessary, both approaches can be combined.</p>
+
+<h4>Generating an XSD schema</h4>
+
+<p>As well as obtaining the XML snapshot, it is also possible to obtain an XSD schema that the XML snapshot conforms to.</p>
+
+<pre><code>XmlSnapshot snapshot = ...;
+Element customerAsXml = snapshot.getXmlElement();
+Element customerXsd = snapshot.getXsdElement();
+</code></pre>
+
+<p>This can be useful for some tools. Note that for the XSD to be correct, the object being snapshotted must have non-null values for the paths that are <code>include()</code>'d. If this isn't done then the XSD will not be correct reflect for another snapshotted object that does have non-null values.</p>
+
+<h3>Hints and Tips</h3>
+
+<p>As an alternative to using <code>include()</code>, you might consider building a non-persisted domain object (a "view model") which can reference only the relevant information required for the snapshot.</p>
+
+<p>For example, if only the 5 most recent Orders for a Customer were required, a <code>CustomerAndRecentOrders</code> view model could hold a collection of just those 5 <code>Order</code>s.</p>
+
+<p>Typically such view models would implement <code>SnapshottableWithInclusions</code>.</p>
+
+<h3>Implementation</h3>
+
+<blockquote>
+ <p>TO DOCUMENT</p>
+</blockquote>
+
+<h3>Registering the Service</h3>
+
+<blockquote>
+ <p>TO DOCUMENT</p>
+</blockquote>
+
+<h3>Related Services</h3>
+
+<blockquote>
+ <p>TO DOCUMENT</p>
+</blockquote>
+
+
+
+ </div>
+
+ <div id="edit" class="modal hide fade in" style="xxxdisplay: none; ">
+ <div class="modal-header">
+ <a class="close" data-dismiss="modal">x</a>
+
+ <h3>Thank you for contributing to the documention!</h3>
+ </div>
+ <div class="modal-body">
+ <h4>Any help with the documentation is greatly appreciated.</h4>
+ <p>All edits are reviewed before going live, so feel free to do much more than fix typos or links. If you see a page that could benefit from an entire rewrite, we'd be thrilled to review it. Don't be surprised if we like it so much we ask you for help with other pages :)</p>
+ <small>NOTICE: unless indicated otherwise on the pages in question, all editable content available from apache.org is presumed to be licensed under the Apache License (AL) version 2.0 and hence all submissions to apache.org treated as formal Contributions under the license terms.</small>
+ <!--[if gt IE 6]>
+ <h4>Internet Explorer Users</h4>
+ <p>If you are not an Apache committer, click the Yes link and enter a <i>anonymous</i> for the username and leave the password empty</p>
+ <![endif]-->
+
+ </div>
+ <div class="modal-footer">
+ Do you have an Apache ID?
+ <a href="javascript:void(location.href='https://cms.apache.org/redirect?uri='+escape(location.href))" class="btn">Yes</a>
+ <a href="javascript:void(location.href='https://anonymous:@cms.apache.org/redirect?uri='+escape(location.href))" class="btn">No</a>
+ </div>
+ </div>
+ <!--
+ <script src="./../../javascript/bootstrap-modal.js"></script>
+ -->
+
+ <footer>
+ <hr/>
+ <p>
+ Copyright © 2010~2014 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.
+ <br/>
+ Apache Isis, Isis, Apache, the Apache feather logo, and the Apache Isis project logo are trademarks of The Apache Software Foundation.
+ </p>
+ </footer>
+
+ </div> <!-- /container -->
+
+ </body>
+</html>
Added: websites/staging/isis/trunk/content/reference/value-types.html
==============================================================================
--- websites/staging/isis/trunk/content/reference/value-types.html (added)
+++ websites/staging/isis/trunk/content/reference/value-types.html Mon Feb 10 21:28:21 2014
@@ -0,0 +1,575 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+
+ <meta charset="utf-8">
+ <title>Value Types
</title>
+ <meta name="description" content="">
+ <meta name="author" content="">
+
+ <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
+ <!--[if lt IE 9]>
+ <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
+ <![endif]-->
+
+
+ <!-- Le styles -->
+ <link href="./../bootstrap-3.0.0/css/bootstrap.css" rel="stylesheet">
+ <link href="./../prettify.css" rel="stylesheet">
+
+ <style type="text/css">
+ body {
+ padding-top: 60px;
+ }
+ .sprite {
+ display: inline-block;
+ height: 20px;
+ margin: 0 auto 4px;
+ outline: medium none;
+ text-indent: -999em;
+ width: 24px;
+ background-image: url('./../images/sprites.png');
+ background-repeat: no-repeat;
+ overflow: hidden;
+ cursor: pointer;
+ }
+ .edit-page {
+ display: inline-block;
+ height: 20px;
+ margin: 0 auto 4px;
+ outline: medium none;
+ text-indent: -999em;
+ width: 24px;
+ background-image: url('./../images/edit.png');
+ background-repeat: no-repeat;
+ overflow: hidden;
+ cursor: pointer;
+ }
+ .fb-share {
+ background-position: 0px -40px;
+ }
+ .gp-share {
+ background-position: 0px 0px;
+ }
+ .tw-share {
+ background-position: 0px -80px;
+ }
+ .markdown-content {
+ min-height: 500px;
+ }
+ .book-image img {
+ border: 1px;
+ border-style: solid;
+ }
+ .release-matrix .heading {
+ background-color: #eeeeee;
+ }
+ .release-matrix .new {
+ color: #dd0000;
+ font-weight: bolder;
+ }
+ .stub,.note {
+ position: relative;
+ padding: 7px 15px;
+ margin-bottom: 18px;
+ color: #404040;
+ background-color: #eedc94;
+ background-repeat: repeat-x;
+ background-image: -khtml-gradient(linear, left top, left bottom, from(#fceec1), to(#eedc94));
+ background-image: -moz-linear-gradient(top, #fceec1, #eedc94);
+ background-image: -ms-linear-gradient(top, #fceec1, #eedc94);
+ background-image: -webkit-gradient(linear, left top, left bottom, color-stop(0%, #fceec1), color-stop(100%, #eedc94));
+ background-image: -webkit-linear-gradient(top, #fceec1, #eedc94);
+ background-image: -o-linear-gradient(top, #fceec1, #eedc94);
+ background-image: linear-gradient(top, #fceec1, #eedc94);
+ filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#fceec1', endColorstr='#eedc94', GradientType=0);
+ text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.25);
+ border-color: #eedc94 #eedc94 #e4c652;
+ border-color: rgba(0, 0, 0, 0.1) rgba(0, 0, 0, 0.1) rgba(0, 0, 0, 0.25);
+ text-shadow: 0 1px 0 rgba(255, 255, 255, 0.5);
+ border-width: 1px;
+ border-style: solid;
+ -webkit-border-radius: 4px;
+ -moz-border-radius: 4px;
+ border-radius: 4px;
+ -webkit-box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.25);
+ -moz-box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.25);
+ box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.25);
+ }
+
+ div.XXXisis-tweak form {
+ margin-top: 6px;
+ margin-bottom: -2px;
+ }
+
+ div.row div.col-md-12 {
+ border-top: 1px solid #eeeeee;
+ }
+
+
+ /* Isis specific stuff */
+
+ .container {
+ width: 940px;
+ }
+
+ .markdown-content .documentation .span-one-third p {
+ margin-bottom: 0px;
+ }
+
+ .markdown-content .documentation .group {
+ margin-top: 9px;
+ }
+
+ .documentation .group h2 {
+ border-bottom: 1px solid #DDD
+ }
+ .documentation h2 a, .documentation h3 a {
+ /* same as code style */
+ padding: 0 3px 2px;
+ font-family: Monaco, Andale Mono, Courier New, monospace;
+ font-size: 12px;
+ -webkit-border-radius: 3px;
+ -moz-border-radius: 3px;
+ border-radius: 3px;
+ padding: 1px 3px;
+ }
+
+ .carousel-indicators li {
+ border: 1px solid rgb(192,70,1);
+ }
+
+ .carousel-indicators li.active {
+ background-color: rgb(192,70,1);
+ }
+
+ .carousel-control .icon-prev,
+ .carousel-control .icon-next {
+ color: rgb(192,70,1);
+ font-size: 60px;
+ }
+
+ .page-header {
+ margin-top: 0px;
+ }
+
+ </style>
+ <script type="text/javascript">
+ function fbshare () {
+ window.open(
+ "http://www.facebook.com/sharer/sharer.php?u="+document.URL,
+ 'Share on Facebook',
+ 'width=640,height=426');
+ };
+ function gpshare () {
+ window.open(
+ "https://plus.google.com/share?url="+document.URL,
+ 'Share on Google+',
+ 'width=584,height=385');
+ };
+ function twshare () {
+ window.open(
+ "https://twitter.com/intent/tweet?url="+document.URL+"&text=Value Types
",
+ 'Share on Twitter',
+ 'width=800,height=526');
+ };
+ </script>
+
+ <!-- Le fav and touch icons -->
+ <link rel="shortcut icon" href="./../images/favicon.ico">
+
+ <script src="./../javascript/prettify.js" type="text/javascript"></script>
+
+ <script src="//code.jquery.com/jquery.js"></script>
+ <script src="./../javascript/prettyprint.js"></script>
+ <script src="./../bootstrap-3.0.0/js/bootstrap.js"></script>
+
+
+ <script src="http://platform.twitter.com/widgets.js" type="text/javascript"></script>
+ <!--
+ <DISABLEDscript src="./../javascript/common.js"></DISABLEDscript>
+ -->
+
+
+
+
+
+ <script>
+ $(function () { prettyPrint() })
+ $().dropdown()
+ </script>
+
+ </head>
+
+ <body>
+
+ <nav class="navbar navbar-fixed-top navbar-inverse" role="navigation">
+ <div class="container">
+ <a class="navbar-brand" href="./../index.html">Apache Isis™</a>
+ <ul class="nav navbar-nav">
+ <li><a href="./../download.html">Download</a></li>
+ <li><a href="./../documentation.html">Documentation</a></li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Screenshots<b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a href="./../getting-started/screenshots.html">Screenshots</a></li>
+ <li><a href="./../getting-started/screencasts.html">Screencasts</a></li>
+ <li><a href="./../getting-started/powered-by.html">Powered by</a></li>
+ <li><a href="http://isisdemo.mmyco.co.uk/">Online Demo</a></li>
+ </ul>
+ </li>
+
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Support<b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a href="./../support.html">Mailing Lists</a></li>
+ <li><a href="http://isis.markmail.org/search/?q=">ML Archives</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/ISIS">JIRA</a></li>
+ <li><a href="http://stackoverflow.com/questions/tagged/isis">Stack Overflow</a></li>
+ <li><a href="http://github.com/apache/isis">Github mirror</a></li>
+ </ul>
+ </li>
+
+ <FORM class="navbar-form navbar-right" id="searchbox_012614087480249044419:dn-q5gtwxya" action="http://www.google.com/cse">
+ <div class="form-group">
+ <input type="hidden" name="cx" value="012614087480249044419:dn-q5gtwxya">
+ <INPUT type="hidden" name="cof" value="FORID:0">
+ <INPUT class="form-control" name="q" type="text" placeholder="Search">
+ </div>
+ </FORM>
+
+ <li class="dropdown navbar-right">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Apache <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li>
+ <a href="http://www.apache.org/">Apache Homepage <i class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/licenses/">Licenses <i class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/security/">Security <i class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship <i class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="http://www.apache.org/foundation/thanks.html">Thanks <i class="icon-share-alt"></i></a>
+ </li>
+ <li>
+ <a href="./../more-thanks.html">More thanks <i class="icon-share-alt"></i></a>
+ </li>
+ </ul>
+ </li>
+ </ul>
+
+ </div>
+ </nav>
+
+ <div class="container">
+ <div class="markdown-content">
+
+
+<div class="page-header">
+<p><a href="./../documentation.html">Docs</a> » <a href="./../reference/about.html">Reference</a></p>
+<h1>Value Types
+
+</h1>
+</div>
+
+<p>The state of any given entity is characterized by properties <!--(?)--> and
+collections <!--(?)-->. A collections is a one-to-many reference to another
+entities, while a property is either a one-to-one reference to another
+entity, or it is a value.</p>
+
+<p>But what's a value? Well, it's an atomic piece of state. A string is a
+value, so is a number, so is a date. Values should be designed to be
+immutable (though some system value types, such as java.util.Date,
+famously are not).</p>
+
+<p><em>Isis</em> supports all the standard JDK value types, and defines a number
+of its own (eg Percentage and Color). <em>Isis</em> also allows you to define
+your own value types, such as <code>LastName</code>, or <code>Celsius</code>, or <code>ComplexNumber</code>.</p>
+
+<p>It's also possible to make Isis integrate with third-party
+value types. <em>Isis</em> provides one such integration, with
+<a href="http://joda-time.sourceforge.net/">JodaTime</a>.</p>
+
+<blockquote>
+ <p><strong>Note</strong></p>
+
+ <p><em>Isis</em>' support for a particular value type does not necessarily imply
+ that there is a custom widget for that type in a particular viewer.
+ Rather, it means that the state of the object can be serialized, is
+ expected to have equal-by-content semantics, and is expected to be
+ immutable. It may also be parseable from a string.</p>
+
+ <p>Also, if using the JDO/DataNucleus ObjectStore, you may also need to perform additional DataNucleus-specific configuration if you want the data to be persisted in a SQL datatype other than SQL Blob (ie a serializable byte array).</p>
+</blockquote>
+
+<h2>Built-in value types</h2>
+
+<p>The following are the value types supported by <em>Isis</em> out-of-the-box.</p>
+
+<h3>JDK Types</h3>
+
+<p>The following JDK types are supported by <em>Isis</em>.</p>
+
+<h4>Primitive Types</h4>
+
+<p>All the primitive types may be used as values: <code>byte</code>, <code>short</code>, <code>int</code>, <code>long</code>, <code>float</code>, <code>double</code>, <code>char</code>, and <code>boolean</code>.</p>
+
+<h4>Wrapper Types</h4>
+
+<p>The wrapper types for each of the primitives can also be used as value types: <code>java.lang.Byte</code>, <code>java.lang.Short</code>, <code>java.lang.Integer</code>, <code>java.lang.Long</code>, <code>java.lang.Float</code>, <code>java.lang.Double</code>, <code>java.lang.Character</code>, <code>java.lang.Boolean</code>.</p>
+
+<h4>Java Classes</h4>
+
+<p>The following java classes have value semantics and may be used as value types:</p>
+
+<ul>
+<li><code>java.lang.String</code></li>
+<li><code>java.math.BigInteger</code> and <code>java.math.BigDecimal</code></li>
+<li><code>java.util.Date</code> (date and time), <code>java.sql.Date</code> (date only), and <code>java.sql.Time</code> (time only)</li>
+<li><code>java.sql.Timestamp</code></li>
+<li><code>java.awt.Image</code></li>
+</ul>
+
+<h4>JODA</h4>
+
+<p>The following <a href="http://joda-time.sourceforge.net/">Joda</a> types are also supported:</p>
+
+<ul>
+<li><code>org.joda.time.LocalDate</code></li>
+<li><code>org.joda.time.LocalDateTime</code></li>
+<li><code>org.joda.time.DateTime</code></li>
+</ul>
+
+<h4>Isis AppLib</h4>
+
+<p><em>Isis</em> itself also provides a number of its own value types. These are
+all in the <code>org.apache.applib.value</code> package:</p>
+
+<ul>
+<li><code>Color</code></li>
+<li><code>Date</code> (date only), <code>DateTime</code> (date and time) and <code>Time</code> (time only)</li>
+<li><code>TimeStamp</code></li>
+<li><code>Image</code></li>
+<li><code>Money</code></li>
+<li><code>Password</code></li>
+<li><code>Percentage</code></li>
+</ul>
+
+<h2>Custom value types</h2>
+
+<p>In addition to the built-in value types it is also possible to define user-defined value types. This is typically done using the <code>@Value</code> annotation.</p>
+
+<p>The <code>@Value</code> annotation is used to provide an implementation of the <code>org.apache.isis.applib.adapters.ValueSemanticsProvider</code> interface. In turn this provides objects that allow the framework to interact with the value, specifically:</p>
+
+<ul>
+<li>the <code>EncoderDecoder</code> is used to convert the value into and back out of serializable form</p>
+
+<p>This is used by some object stores (eg the XML Object Store), for by the XML Snapshot capability <!--(see ?)-->;</li>
+<li>the <code>Parser</code> is used to convert Strings into the value type</p>
+
+<p>This is used as a fallback by viewers that do not have any specific widgets to support the particular value type, and make do with a simple text field instead.</p>
+
+<p>An obvious example is to parse a date. But it could be used to parse "TRUE" and "FALSE" into a boolean (as opposed to using a checkbox).</li>
+<li>the <code>DefaultsProvider</code> is used to provide a meaningful default for the value</p>
+
+<p>Not every value type will have a default, but some do (eg false for a boolean, 0 for a number). This is used as the default value for non-<code>@Optional</code> properties and parameters.</li>
+</ul>
+
+<p>Each of these interfaces also reside in <code>org.apache.isis.applib.adapters</code>.</p>
+
+<p>For more details, explore the built-in types within the applib, for example <code>org.apache.isis.applib.value.Money</code>.</p>
+
+<pre><code>@Value(semanticsProviderName = "org.apache.isis.core.progmodel.facets.value.MoneyValueSemanticsProvider")
+public class Money extends Magnitude {
+ ...
+}
+</code></pre>
+
+<p>where <code>MoneyValueSemanticsProvider</code> is the implementation of
+<code>ValueSemanticsProvider</code> described above.</p>
+
+<blockquote>
+ <p><strong>Note</strong></p>
+
+ <p>Using value types generally removes the need for using <code>@MustSatisfy</code> annotation <!--(see ?)-->; the rules can
+ instead move down into a <code>validate()</code> method on the value type itself.</p>
+</blockquote>
+
+<h2>Third-party value types</h2>
+
+<p>Third party value types can also supported, again
+through the use of a <code>ValueSemanticsProvider</code>. However, since the source code cannot be altered, the provider must be supplied using a key value in <code>isis.properties</code> configuration file.</p>
+
+<p>For example, the following would register a semantics provider for <code>org.jodatime.time.Interval</code> (not a built-in at the time of this writing):</p>
+
+<pre><code> isis.core.progmodel.value.org.jodatime.time.DateTime.semanticsProviderName=\
+ com.mycompany.values.JodaIntervalValueSemanticsProvider
+</code></pre>
+
+<h2>Value formats</h2>
+
+<blockquote>
+ <p><strong>note</strong> this feature is only partially support by some viewers (eg Wicket viewer)</p>
+</blockquote>
+
+<p><em>Isis</em> provides default formats for the inbuilt value types, according
+to type. These can be modified using <code>isis.properties</code>.</p>
+
+<p>These formats cut across the above categories; for example the byte
+format relates to both byte (primitive) and java.lang.Byte (wrapper). In
+all cases this setting can be overriden for a specific field using the
+@Mask annotation (see ?).</p>
+
+<h4>Byte format</h4>
+
+<p>The format for all bytes can be set, replacing the default format
+derived from the system, using the following property to specify a mask:</p>
+
+<pre><code>isis.value.format.byte=####
+</code></pre>
+
+<p>The mask is used to set up a java.text.DecimalFormat formatting object
+so details of the mask format can be found in the Java documentation.</p>
+
+<h4>Date Format</h4>
+
+<p>The format for all dates can be set, replacing the default format derived from the system, using the following property to specify one of <em>long</em>, <em>medium</em>, <em>short</em>, <em>isolong</em>, <em>isoshort</em> or a mask:</p>
+
+<pre><code>isis.value.format.date=dd/MM/yy
+</code></pre>
+
+<p>When a mask is specified it is used to set up a
+<code>java.text.SimpleDateFormat</code> formatting object so details of the mask format can be found in the Java documentation.</p>
+
+<h4>Date/time Format</h4>
+
+<p>The format for all date/time values can be set, replacing the default format derived from the system, using the following property to specify one of <em>long</em>, <em>medium</em>, <em>short</em>, <em>isolong</em>, <em>isoshort</em> or a mask:</p>
+
+<pre><code>isis.value.format.datetime=dd/MM/yy
+</code></pre>
+
+<p>When a mask is specified it is used to set up a
+<code>java.text.SimpleDateFormat</code> formatting object so details of the mask format can be found in the Java documentation.</p>
+
+<h4>Decimal format</h4>
+
+<p>The format for <code>BigDecimal</code> values can be set, replacing the default format derived from the system, using the following property to specify a mask:</p>
+
+<pre><code>isis.value.format.decimal=####
+</code></pre>
+
+<p>The mask is used to set up a <code>java.text.DecimalFormat</code> formatting object so details of the mask format can be found in the Java documentation.</p>
+
+<h4>Double format</h4>
+
+<p>The format for all double values can be set, replacing the default format derived from the system, using the following property to specify a mask:</p>
+
+<pre><code>isis.value.format.double=####
+</code></pre>
+
+<p>The mask is used to set up a <code>java.text.DecimalFormat</code> formatting object so details of the mask format can be found in the Java documentation.</p>
+
+<h4>Float format</h4>
+
+<p>The format for all float values can be set, replacing the default format derived from the system, using the following property to specify a mask:</p>
+
+<pre><code>isis.value.format.float=####
+</code></pre>
+
+<p>The mask is used to set up a <code>java.text.DecimalFormat</code> formatting object so details of the mask format can be found in the Java documentation.</p>
+
+<h4>Integer format</h4>
+
+<p>The format for all integers (including <code>BigInteger</code>) can be set, replacing the default format derived from the system, using the following property to specify a mask:</p>
+
+<pre><code>isis.value.format.int=####
+</code></pre>
+
+<p>The mask is used to set up a <code>java.text.DecimalFormat</code> formatting object so details of the mask format can be found in the Java documentation.</p>
+
+<h4>Long format</h4>
+
+<p>The format for all long values can be set, replacing the default format derived from the system, using the following property to specify a mask:</p>
+
+<pre><code>isis.value.format.long=####
+</code></pre>
+
+<p>The mask is used to set up a <code>java.text.DecimalFormat</code> formatting object so details of the mask format can be found in the Java documentation.</p>
+
+<h4>Short format</h4>
+
+<p>The format for all short values can be set, replacing the default format derived from the system, using the following property to specify a mask:</p>
+
+<pre><code>isis.value.format.short=####
+</code></pre>
+
+<p>The mask is used to set up a <code>java.text.DecimalFormat</code> formatting object so details of the mask format can be found in the Java documentation.</p>
+
+<h4>Time Format</h4>
+
+<p>The format for all time values can be set, replacing the default format derived from the system, using the following property to specify one of <em>long</em>, <em>medium</em>, <em>short</em>, <em>isolong</em>, <em>isoshort</em> or a mask:</p>
+
+<pre><code>isis.value.format.time=ddMMyyyy hhmm
+</code></pre>
+
+<p>When a mask is specified it is used to set up a
+<code>java.text.SimpleDateFormat</code> formatting object so details of the mask format can be found in the Java documentation.</p>
+
+<h4>Timestamp Format</h4>
+
+<p>The format for time stamp values can be set, replacing the default format derived from the system, using the following property to specify one of <em>long</em>, <em>medium</em>, <em>short</em>, <em>isolong</em>, <em>isoshort</em> or a mask:</p>
+
+<pre><code>isis.value.format.timestamp=hh:mm
+</code></pre>
+
+<p>When a mask is specified it is used to set up a
+<code>java.text.SimpleDateFormat</code> formatting object so details of the mask format can be found in the Java documentation.</p>
+
+
+
+ </div>
+
+ <div id="edit" class="modal hide fade in" style="xxxdisplay: none; ">
+ <div class="modal-header">
+ <a class="close" data-dismiss="modal">x</a>
+
+ <h3>Thank you for contributing to the documention!</h3>
+ </div>
+ <div class="modal-body">
+ <h4>Any help with the documentation is greatly appreciated.</h4>
+ <p>All edits are reviewed before going live, so feel free to do much more than fix typos or links. If you see a page that could benefit from an entire rewrite, we'd be thrilled to review it. Don't be surprised if we like it so much we ask you for help with other pages :)</p>
+ <small>NOTICE: unless indicated otherwise on the pages in question, all editable content available from apache.org is presumed to be licensed under the Apache License (AL) version 2.0 and hence all submissions to apache.org treated as formal Contributions under the license terms.</small>
+ <!--[if gt IE 6]>
+ <h4>Internet Explorer Users</h4>
+ <p>If you are not an Apache committer, click the Yes link and enter a <i>anonymous</i> for the username and leave the password empty</p>
+ <![endif]-->
+
+ </div>
+ <div class="modal-footer">
+ Do you have an Apache ID?
+ <a href="javascript:void(location.href='https://cms.apache.org/redirect?uri='+escape(location.href))" class="btn">Yes</a>
+ <a href="javascript:void(location.href='https://anonymous:@cms.apache.org/redirect?uri='+escape(location.href))" class="btn">No</a>
+ </div>
+ </div>
+ <!--
+ <script src="./../javascript/bootstrap-modal.js"></script>
+ -->
+
+ <footer>
+ <hr/>
+ <p>
+ Copyright © 2010~2014 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.
+ <br/>
+ Apache Isis, Isis, Apache, the Apache feather logo, and the Apache Isis project logo are trademarks of The Apache Software Foundation.
+ </p>
+ </footer>
+
+ </div> <!-- /container -->
+
+ </body>
+</html>