blob: 41b45585833c77cce3263411b20a1e79d93e1deb [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Identifiers :: Apache Isis</title>
<link rel="canonical" href="https://isis.apache.org/userguide/2.0.0-M4/fun/overview/identifiers.html">
<meta name="generator" content="Antora 2.3.4">
<link rel="stylesheet" href="../../../../_/css/site.css">
<link rel="stylesheet" href="../../../../_/css/site-custom.css">
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300,300i,400,400i,700,700i|Raleway:300,400,500,700,800|Montserrat:300,400,700" rel="stylesheet">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css"/>
<link rel="home" href="https://isis.apache.org" title="Apache Isis">
</head>
<body class="article">
<header class="header">
<nav class="navbar">
<div class="navbar-brand">
<a class="navbar-item" href="https://isis.apache.org">
<span class="icon">
<img src="../../../../_/img/isis-logo-48x48.png"></img>
</span>
<span>Apache Isis</span>
</a>
<button class="navbar-burger" data-target="topbar-nav">
<span></span>
<span></span>
<span></span>
</button>
</div>
<div id="topbar-nav" class="navbar-menu">
<a class="navbar-end">
<div class="navbar-item hide-for-print">
<span>
<input id="algolia-search-input" placeholder="Search"></span>
</span>
</div>
<div class="navbar-item has-dropdown is-hoverable">
<a class="navbar-link" href="#">Quick Start</a>
<div class="navbar-dropdown">
<span class="navbar-item navbar-heading">Starter Apps</span>
<a class="navbar-item" href="../../../../docs/2.0.0-M4/starters/helloworld.html">Hello World</a>
<a class="navbar-item" href="../../../../docs/2.0.0-M4/starters/simpleapp.html">Simple App</a>
<hr class="navbar-divider"/>
<span class="navbar-item navbar-heading">Demos &amp; Tutorials</span>
<a class="navbar-item" href="../../../../docs/2.0.0-M4/demo/about.html">Demo App</a>
<a class="navbar-item" href="https://danhaywood.gitlab.io/isis-petclinic-tutorial-docs/petclinic/1.16.2/intro.html">Petclinic (tutorial)</a>
<hr class="navbar-divider"/>
<span class="navbar-item navbar-heading">Resources</span>
<a class="navbar-item" href="../../../../docs/2.0.0-M4/resources/cheatsheet.html">Cheatsheet</a>
<a class="navbar-item" href="../../../../docs/2.0.0-M4/resources/icons.html">Icons</a>
</div>
</div>
<div class="navbar-item has-dropdown is-hoverable">
<a class="navbar-link" href="#">Guides</a>
<div class="navbar-dropdown">
<span class="navbar-item navbar-heading">Development</span>
<a class="navbar-item" href="../../../../setupguide/2.0.0-M4/about.html">Setup Guide</a>
<hr class="navbar-divider"/>
<span class="navbar-item navbar-heading">Core</span>
<a class="navbar-item" href="../../../../userguide/2.0.0-M4/about.html">User Guide</a>
<a class="navbar-item" href="../../../../refguide/2.0.0-M4/about.html">Reference Guide</a>
<a class="navbar-item" href="../../../../testing/2.0.0-M4/about.html">Testing Guide</a>
</div>
</div>
<div class="navbar-item has-dropdown is-hoverable">
<a class="navbar-link" href="#">Libraries</a>
<div class="navbar-dropdown">
<span class="navbar-item navbar-heading">For Use in Apps</span>
<a class="navbar-item" href="../../../../subdomains/2.0.0-M4/about.html">Subdomain Libraries</a>
<a class="navbar-item" href="../../../../valuetypes/2.0.0-M4/about.html">Value Types</a>
<hr class="navbar-divider"/>
<span class="navbar-item navbar-heading">Integrate between Apps</span>
<a class="navbar-item" href="../../../../mappings/2.0.0-M4/about.html">Bounded Context Mapping Libraries</a>
<hr class="navbar-divider"/>
<span class="navbar-item navbar-heading">Other</span>
<a class="navbar-item" href="../../../../incubator/2.0.0-M4/about.html">Incubator</a>
<a class="navbar-item" href="../../../../legacy/2.0.0-M4/about.html">Legacy</a>
</div>
</div>
<div class="navbar-item has-dropdown is-hoverable">
<a class="navbar-link" href="#">Components</a>
<div class="navbar-dropdown">
<span class="navbar-item navbar-heading">Viewers</span>
<a class="navbar-item" href="../../../../vw/2.0.0-M4/about.html">Wicket UI</a>
<a class="navbar-item" href="../../../../vro/2.0.0-M4/about.html">Restful Objects (REST)</a>
<hr class="navbar-divider"/>
<span class="navbar-item navbar-heading">Security</span>
<a class="navbar-item" href="../../../../security/2.0.0-M4/about.html">Security Guide</a>
<hr class="navbar-divider"/>
<span class="navbar-item navbar-heading">Persistence</span>
<a class="navbar-item" href="../../../../pjdo/2.0.0-M4/about.html">DataNucleus (JDO)</a>
<hr class="navbar-divider"/>
<span class="navbar-item navbar-heading">Extensions</span>
<a class="navbar-item" href="../../../../extensions/2.0.0-M4/about.html">Extensions Catalog</a>
</div>
</div>
<div class="navbar-item has-dropdown is-hoverable">
<a class="navbar-link" href="#">Support</a>
<div class="navbar-dropdown">
<span class="navbar-item navbar-heading">Contact</span>
<a class="navbar-item" href="../../../../docs/2.0.0-M4/support/slack-channel.html">Slack</a>
<a class="navbar-item" href="../../../../docs/2.0.0-M4/support/mailing-list.html">Mailing Lists</a>
<a class="navbar-item" href="https://issues.apache.org/jira/browse/ISIS">JIRA</a>
<a class="navbar-item" href="https://stackoverflow.com/questions/tagged/isis">Stack Overflow</a>
<hr class="navbar-divider"/>
<span class="navbar-item navbar-heading">Releases</span>
<a class="navbar-item" href="../../../../docs/2.0.0-M4/downloads/how-to.html">Downloads</a>
<a class="navbar-item" href="../../../../relnotes/2.0.0-M4/about.html">Release Notes</a>
<a class="navbar-item" href="../../../../docs/2.0.0-M4/archive/1-x.html">Archive (1.x)</a>
<hr class="navbar-divider"/>
<span class="navbar-item navbar-heading">Framework</span>
<a class="navbar-item" href="../../../../conguide/2.0.0-M4/about.html">Contributors' Guide</a>
<a class="navbar-item" href="../../../../comguide/2.0.0-M4/about.html">Committers' Guide</a>
<a class="navbar-item" href="../../../../core/2.0.0-M4/about.html">Core Design</a>
</div>
</div>
<div class="navbar-item has-dropdown is-hoverable">
<a class="navbar-link" href="#">ASF</a>
<div class="navbar-dropdown">
<a class="navbar-item" href="http://www.apache.org/">Apache Homepage</a>
<a class="navbar-item" href="https://www.apache.org/events/current-event">Events</a>
<a class="navbar-item" href="https://www.apache.org/licenses/">Licenses</a>
<a class="navbar-item" href="https://www.apache.org/security/">Security</a>
<a class="navbar-item" href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
<a class="navbar-item" href="https://www.apache.org/foundation/thanks.html">Thanks</a>
<hr class="navbar-divider"/>
<a class="navbar-item" href="https://whimsy.apache.org/board/minutes/Isis.html">PMC board minutes</a>
</div>
</div>
<a class="navbar-item" href="../../../../docs/2.0.0-M4/about.html">
<span class="icon">
<img src="../../../../_/img/home.png"></img>
</span>
</a>
</div>
</div>
</nav>
</header>
<div class="body ">
<div class="nav-container" data-component="userguide" data-version="2.0.0-M4">
<aside class="nav">
<div class="panels">
<div class="nav-panel-pagination">
<a class="page-previous disabled" rel="prev" href="" title=""><span></span></a>
<a class="page-next disabled" rel="next"
href="" title=""><span></span></a>
<!--
page.parent doesn't seem to be set...
<a class="page-parent disabled" rel="prev" href="" title=""><span></span></a>
-->
</div>
<div class="nav-panel-menu is-active" data-panel="menu">
<nav class="nav-menu">
<h3 class="title"><a href="../../about.html">User Guide</a></h3>
<ul class="nav-list">
<li class="nav-item" data-depth="0">
<ul class="nav-list">
<li class="nav-item" data-depth="1">
<a class="nav-link" href="../concepts-patterns.html">Concepts &amp; Patterns</a>
</li>
<li class="nav-item" data-depth="1">
<a class="nav-link" href="../overview.html">Overview</a>
</li>
<li class="nav-item" data-depth="1">
<a class="nav-link" href="../domain-entities-and-services.html">Domain Entities &amp; Services</a>
</li>
<li class="nav-item" data-depth="1">
<a class="nav-link" href="../object-members.html">Object Members</a>
</li>
<li class="nav-item" data-depth="1">
<a class="nav-link" href="../ui.html">UI Layout &amp; Hints</a>
</li>
<li class="nav-item" data-depth="1">
<a class="nav-link" href="../business-rules.html">Business Rules</a>
</li>
<li class="nav-item" data-depth="1">
<a class="nav-link" href="../drop-downs-and-defaults.html">Drop downs and Defaults</a>
</li>
<li class="nav-item" data-depth="1">
<a class="nav-link" href="../meta-annotations.html">Meta-annotations</a>
</li>
<li class="nav-item" data-depth="1">
<a class="nav-link" href="../view-models.html">View Models</a>
</li>
<li class="nav-item" data-depth="1">
<a class="nav-link" href="../mixins.html">Mixins</a>
</li>
<li class="nav-item" data-depth="1">
<a class="nav-link" href="../modules.html">Modules</a>
</li>
<li class="nav-item" data-depth="1">
<button class="nav-item-toggle"></button>
<a class="nav-link" href="../../btb/about.html">Beyond the Basics</a>
<ul class="nav-list">
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../../btb/i18n.html">i18n</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../../btb/headless-access.html">Headless Access</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../../btb/hints-and-tips.html">Hints-n-Tips</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../../btb/programming-model.html">Programming Model</a>
</li>
</ul>
</li>
<li class="nav-item" data-depth="1">
<button class="nav-item-toggle"></button>
<span class="nav-text">Extensions</span>
<ul class="nav-list">
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../../flyway/about.html">Flyway</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../../quartz/about.html">Quartz</a>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</nav>
</div>
<div class="nav-panel-explore" data-panel="explore">
<div class="context">
<span class="title">User Guide</span>
<span class="version">2.0.0-M4</span>
</div>
<ul class="components">
<li class="component">
<span class="title"> </span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../docs/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">BC Mappings Catalog</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../mappings/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">Committers' Guide</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../comguide/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">Contributors' Guide</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../conguide/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">Design Docs</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../core/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">Extensions Catalog</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../extensions/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">Incubator Catalog</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../incubator/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">JDO/DataNucleus</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../pjdo/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">Legacy Catalog</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../legacy/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">Reference Guide</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../refguide/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">Release Notes</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../relnotes/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">Restful Objects Viewer</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../vro/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">Security Guide</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../security/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">Setup Guide</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../setupguide/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">Subdomains Catalog</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../subdomains/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">System Overview</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../system/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">Testing Guide</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../testing/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component is-current">
<span class="title">User Guide</span>
<ul class="versions">
<li class="version is-current is-latest">
<a href="../../about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">Value Types Catalog</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../valuetypes/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
<li class="component">
<span class="title">Wicket Viewer</span>
<ul class="versions">
<li class="version is-latest">
<a href="../../../../vw/2.0.0-M4/about.html">2.0.0-M4</a>
</li>
</ul>
</li>
</ul>
</div>
</div>
</aside>
</div>
<main role="main">
<div class="toolbar" role="navigation">
<button class="nav-toggle"></button>
<a href="../../../../docs/2.0.0-M4/about.html" class="home-link"></a>
<nav class="breadcrumbs" aria-label="breadcrumbs">
<ul>
<li><a href="../../about.html">User Guide</a></li>
<li><a href="identifiers.html">Identifiers</a></li>
</ul>
</nav>
<div class="edit-this-page"><a href="https://github.com/apache/isis/edit/2.0.0-M4/api/adoc/userguide/modules/fun/pages/overview/identifiers.adoc">Edit</a></div>
</div>
<article class="doc">
<a name="section-top"></a>
<h1 class="page">Identifiers</h1>
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>The Apache Isis framework tracks the identity of each domain object.
This identity is represented to the end-user in human-readable form so that they know which object they are interacting with, and is also used and is available internally/for integrations.</p>
</div>
<div class="paragraph">
<p>This section explores these two related concepts.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="title-and-icon-and-css-class"><a class="anchor" href="#title-and-icon-and-css-class"></a>Title, Icon etc.</h2>
<div class="sectionbody">
<div class="paragraph">
<p>To allow the end-user to distinguish one domain object from another, it is rendered with a title and an icon.
The icon informally identifies the type of the domain object, while the title identifies the instance.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Title</p>
<div class="paragraph">
<p>The title of a domain object is shown in several places: as the main heading for an object; as a link text or tooltip for an object referencing another object, and also in tables representing collections of objects.</p>
</div>
<div class="paragraph">
<p>The title is not formally required to be a unique identify the object within its type, but it needs to be "unique enough" that a human user is able to distinguish one instance from another.</p>
</div>
<div class="paragraph">
<p>The title is usually just a simple string, but the framework also allows for the title to be translated into different locales.</p>
</div>
</li>
<li>
<p>Icon</p>
<div class="paragraph">
<p>Sometimes it&#8217;s helpful for the icon to represent more than just the object&#8217;s type; it might also indicate the state of an object.
For example, a shipped <code>Order</code> might have a slightly different icon to a yet-to-be-shipped <code>Order</code>; or a library book that is <code>loaned out</code> might be distinguished from one that is <code>available</code>.</p>
</div>
</li>
</ul>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Details on how to actually write titles and icons (the programming model) can be found <a href="../ui.html#object-titles-and-icons" class="page">here</a>.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="oid"><a class="anchor" href="#oid"></a>OIDs</h2>
<div class="sectionbody">
<div class="paragraph">
<p>As well as defining a <a href="../concepts-patterns.html#metamodel" class="page">metamodel</a> of the structure (domain classes) of its domain objects, Apache Isis also manages the runtime instances of said domain objects.</p>
</div>
<div class="paragraph">
<p>When a domain entity is recreated from the database, the framework keeps track of its identity through an "OID": an object identifier.
Fundamentally this is a combination of its type (domain class), along with an identifier.
You can think of it as its "primary key", except across all domain entity types.</p>
</div>
<div class="paragraph">
<p>For portability and resilience, though, the object type is generally an alias for the actual domain class: thus "customers.CUS", say, rather than "com.mycompany.myapp.customers.Customer".
This is derived from an annotation.
The identifier meanwhile is always converted to a string.</p>
</div>
<div class="paragraph">
<p>Although simple, the OID is an enormously powerful concept: it represents a URI to any domain object managed by a given Apache Isis application.
With it, we have the ability to lookup any arbitrary domain objects.</p>
</div>
<div class="paragraph">
<p>Some examples:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>an OID allows sharing of information between users, eg as a deep link to be pasted into an email.</p>
</li>
<li>
<p>the information within an OID could be converted into a barcode, and stamped onto a PDF form.
When the PDF is scanned by the mail room, the barcode could be read to attach the correspondence to the relevant domain object.</p>
</li>
<li>
<p>as a handle to any object in an audit record, as used by <a href="../../../../refguide/2.0.0-M4/applib-svc/AuditerService.html" class="page"><code>AuditerService</code></a>;</p>
</li>
<li>
<p>similarly within implementations of <a href="#refguide:applib-svc:CommandServiceInternal.adoc" class="page unresolved"><code>CommandService</code></a> to persist <code>Command</code> objects</p>
</li>
<li>
<p>similarly within implementations of <a href="../../../../refguide/2.0.0-M4/applib-svc/PublisherService.html" class="page"><code>PublisherService</code></a> to persist published action invocations</p>
</li>
<li>
<p>and of course both the <a href="../../../../vro/2.0.0-M4/about.html" class="page">RestfulObjects viewer</a> and <a href="../../../../vw/2.0.0-M4/about.html" class="page">Wicket viewer</a> use the oid tuple to look up, render and allow the user to interact with domain objects.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Although the exact content of an OID should be considered opaque by domain objects, it is possible for domain objects to obtain OIDs.
These are represented as <code>Bookmark</code>s, obtained from the <a href="../../../../refguide/2.0.0-M4/applib-svc/BookmarkService.html" class="page"><code>BookmarkService</code></a>.
Deep links meanwhile can be obtained from the <a href="../../../../refguide/2.0.0-M4/applib-svc/DeepLinkService.html" class="page"><code>DeepLinkService</code></a>.</p>
</div>
<div class="paragraph">
<p>OIDs can also be converted into XML format, useful for integration scenarios.
The <a href="../../../../refguide/2.0.0-M4/schema/common.html" class="page">common schema</a> XSD defines the <code>oidDto</code> complex type for precisely this purpose.</p>
</div>
</div>
</div>
</article>
<aside class="article-aside toc hide-for-print" role="navigation">
<p class="toc-title">On this page</p>
<div id="article-toc"></div>
</aside>
</main>
</div>
<footer class="footer">
<div class="content">
<div class="copyright">
<p>
Copyright © 2010~2020 The Apache Software Foundation, licensed under the Apache License, v2.0.
<br/>
Apache, the Apache feather logo, Apache Isis, and the Apache Isis project logo are all trademarks of The Apache Software Foundation.
</p>
</div>
<div class="revision">
<p>Revision: SNAPSHOT</p>
</div>
</div>
</footer>
<script src="../../../../_/js/site.js"></script>
<script async src="../../../../_/js/vendor/highlight.js"></script>
<script src="../../../../_/js/vendor/jquery-3.4.1.min.js"></script>
<script src="../../../../_/js/vendor/jquery-ui-1.12.1.custom.widget-only.min.js"></script>
<script src="../../../../_/js/vendor/jquery.tocify.min.js"></script>
<script>
$(function() {
$("#article-toc").tocify( {
showEffect: "slideDown",
hashGenerator: "pretty",
hideEffect: "slideUp",
selectors: "h2, h3",
scrollTo: 120,
smoothScroll: true,
theme: "jqueryui",
highlightOnScroll: true
} );
});
</script>
<script src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
<script>
function focusSearchInput () { document.querySelector('#algolia-search-input').focus() }
var search = docsearch({
appId: '5ISP5TFAEN',
apiKey: '0fc51c28b4ad46e7318e96d4e97fab7c',
indexName: 'isis-apache-org',
inputSelector: '#algolia-search-input',
autocompleteOptions: { hint: false, keyboardShortcuts: ['s'] },
debug: false,
}).autocomplete
search.on('autocomplete:closed', function () { search.autocomplete.setVal() })
focusSearchInput()
window.addEventListener('load', focusSearchInput);
</script>
<!--
docsearch options:
https://docsearch.algolia.com/docs/behavior/
-->
<!--
https://www.algolia.com/doc/api-reference/api-parameters/
algoliaOptions: { hitsPerPage: 6 },
-->
</body>
</html>