<!doctype html><htmllang=enclass="js csstransforms3d"><head><metacharset=utf-8><metaname=viewportcontent="width=device-width,initial-scale=1"><metaname=generatorcontent="Hugo 0.80.0"><metaname=descriptioncontent="Strolch is a parameterized framework for use on servers and IoT"><metaname=authorcontent="Robert von Burg"><linkrel=iconhref=/favicon.icotype=image/ico><title>CRUD Book - Strolch</title><linkhref=/css/nucleus.css?1678977092rel=stylesheet><linkhref=/css/fontawesome-all.min.css?1678977092rel=stylesheet><linkhref=/css/hybrid.css?1678977092rel=stylesheet><linkhref=/css/featherlight.min.css?1678977092rel=stylesheet><linkhref=/css/perfect-scrollbar.min.css?1678977092rel=stylesheet><linkhref=/css/auto-complete.css?1678977092rel=stylesheet><linkhref=/css/atom-one-dark-reasonable.css?1678977092rel=stylesheet><linkhref=/css/theme.css?1678977092rel=stylesheet><linkhref=/css/hugo-theme.css?1678977092rel=stylesheet><linkhref=/css/theme-green.css?1678977092rel=stylesheet><scriptsrc=/js/jquery-3.3.1.min.js?1678977092></script><style>:root#header+#content>#left>#rlblock_left{display:none!important}</style></head><bodydata-url=/tutorial/crud-book/><navid=sidebar><divid=header-wrapper><divid=header><aid=logohref=/><imgsrc=/logo.png></a></div><divclass=searchbox><labelfor=search-by><iclass="fas fa-search"></i></label><inputdata-search-inputid=search-bytype=searchplaceholder=Search...>
<spandata-search-clear><iclass="fas fa-times"></i></span></div><scripttype=text/javascriptsrc=/js/lunr.min.js?1678977092></script><scripttype=text/javascriptsrc=/js/auto-complete.js?1678977092></script><scripttype=text/javascript>varbaseurl="https:\/\/strolch.li\/";</script><scripttype=text/javascriptsrc=/js/search.js?1678977092></script></div><sectionid=homelinks><ul><li><aclass=paddinghref=/><iclass="fas fa-home"></i>Home</a></li></ul></section><divclass=highlightable><ulclass=topics><lidata-nav-id=/api/title=APIclass=dd-item><ahref=/api/>API</a></li><lidata-nav-id=/documentation/title=Documentationclass=dd-item><ahref=/documentation/>Documentation</a><ul><lidata-nav-id=/documentation/architecture/title=Architectureclass=dd-item><ahref=/documentation/architecture/>Architecture</a></li><lidata-nav-id=/documentation/model/title=Modelclass=dd-item><ahref=/documentation/model/>Model</a></li><lidata-nav-id=/documentation/do-and-donts/title="Do and Don't"class=dd-item><ahref=/documentation/do-and-donts/>Do and Don't</a></li><lidata-nav-id=/documentation/runtime-configuration/title="Runtime Configuration"class=dd-item><ahref=/documentation/runtime-configuration/>Runtime Configuration</a></li><lidata-nav-id=/documentation/realms/title=Realmsclass=dd-item><ahref=/documentation/realms/>Realms</a></li><lidata-nav-id=/documentation/components/title=Componentsclass=dd-item><ahref=/documentation/components/>Components</a></li><lidata-nav-id=/documentation/services-and-commands/title="Services and Commands"class=dd-item><ahref=/documentation/services-and-commands/>Services and Commands</a></li><lidata-nav-id=/documentation/searches/title=Searchesclass=dd-item><ahref=/documentation/searches/>Searches</a></li><lidata-nav-id=/documentation/queries/title=Queriesclass=dd-item><ahref=/documentation/queries/>Queries</a></li><lidata-nav-id=/documentation/transactions/title=Transactionsclass=dd-item><ahref=/documentation/transactions/>Transactions</a></li><lidata-nav-id=/documentation/policies/title=Policiesclass=dd-item><ahref=/documentation/policies/>Policies</a></li><lidata-nav-id=/documentation/observers/title=Observersclass=dd-item><ahref=/documentation/observers/>Observers</a></li><lidata-nav-id=/documentation/versioning/title=Versioningclass=dd-item><ahref=/documentation/versioning/>Versioning</a></li><lidata-nav-id=/documentation/reports/title=Reportsclass=dd-item><ahref=/documentation/reports/>Reports</a></li><lidata-nav-id=/documentation/priviles/title=Privilegesclass=dd-item><ahref=/documentation/priviles/>Privileges</a></li></ul></li><lidata-nav-id=/plc/title=PLCclass=dd-item><ahref=/plc/>PLC</a><ul><lidata-nav-id=/plc/architecture/title=Architectureclass=dd-item><ahref=/plc/architecture/>Architecture</a></li><lidata-nav-id=/plc/example-set-up/title="Example Set-Up"class=dd-item><ahref=/plc/example-set-up/>Example Set-Up</a></li></ul></li><lidata-nav-id=/tutorial/title=Tutorialclass="dd-item
parent"><ahref=/tutorial/>Tutorial</a><ul><lidata-nav-id=/tutorial/configuration/title=Configurationclass=dd-item><ahref=/tutorial/configuration/>Configuration</a></li><lidata-nav-id=/tutorial/model/title=Modelclass=dd-item><ahref=/tutorial/model/>Model</a></li><lidata-nav-id=/tutorial/crud-book/title="CRUD Book"class="dd-item active"><ahref=/tutorial/crud-book/>CRUD Book</a></li></ul></li><lidata-nav-id=/download/title=Downloadclass=dd-item><ahref=/download/>Download</a></li><lidata-nav-id=/development/title=Developmentclass=dd-item><ahref=/development/>Development</a><ul><lidata-nav-id=/development/prerequisites/title=Prerequisitesclass=dd-item><ahref=/development/prerequisites/>Prerequisites</a></li><lidata-nav-id=/development/building/title="Building Strolch"class=dd-item><ahref=/development/building/>Building Strolch</a></li><lidata-nav-id=/development/maven-archetypes/title="Maven Archetypes"class=dd-item><ahref=/development/maven-archetypes/>Maven Archetypes</a></li><lidata-nav-id=/development/web-app/title="Web App"class=dd-item><ahref=/development/web-app/>Web App</a></li><lidata-nav-id=/development/main-class-app/title="Main Class App"class=dd-item><ahref=/development/main-class-app/>Main Class App</a></li><lidata-nav-id=/development/converting-existing/title="Converting Existing App"class=dd-item><ahref=/development/converting-existing/>Converting Existing App</a></li></ul></li><lidata-nav-id=/blog/title=Blogclass=dd-item><ahref=/blog/>Blog</a><ul><lidata-nav-id=/blog/post-00018/title="Strolch PLC 1.2.3 released"class=dd-item><ahref=/blog/post-00018/>Strolch PLC 1.2.3 released</a></li><lidata-nav-id=/blog/post-00017/title="Strolch 1.8.5 and PLC 1.2.2 are out"class=dd-item><ahref=/blog/post-00017/>Strolch 1.8.5 and PLC 1.2.2 are out</a></li><lidata-nav-id=/blog/post-00016/title="Strolch PLC now also on Maven Central"class=dd-item><ahref=/blog/post-00016/>Strolch PLC now also on Maven Central</a></li><lidata-nav-id=/blog/post-00015/title="Release of Strolch 1.6.100"class=dd-item><ahref=/blog/post-00015/>Release of Strolch 1.6.100</a></li><lidata-nav-id=/blog/post-00014/title="Strolch Reports"class=dd-item><ahref=/blog/post-00014/>Strolch Reports</a></li><lidata-nav-id=/blog/post-00013/title="Strolch Searches"class=dd-item><ahref=/blog/post-00013/>Strolch Searches</a></li><lidata-nav-id=/blog/post-00012/title="Wow, the many changes!"class=dd-item><ahref=/blog/post-00012/>Wow, the many changes!</a></li><lidata-nav-id=/blog/post-00011/title="Strolch now on Maven Central"class=dd-item><ahref=/blog/post-00011/>Strolch now on Maven Central</a></li><lidata-nav-id=/blog/post-00010/title="Versioning of objects"class=dd-item><ahref=/blog/post-00010/>Versioning of objects</a></li><lidata-nav-id=/blog/post-00009/title="Release 1.2.0"class=dd-item><ahref=/blog/post-00009/>Release 1.2.0</a></li><lidata-nav-id=/blog/post-00008/title="Strolch Update"class=dd-item><ahref=/blog/post-00008/>Strolch Update</a></li><lidata-nav-id=/blog/post-00007/title="Activities: Beginning of the planning engine"class=dd-item><ahref=/blog/post-00007/>Activities: Beginning of the planning engine</a></li><lidata-nav-id=/blog/post-00006/title="Strolch Documentation"class=dd-item><ahref=/blog/post-00006/>Strolch Documentation</a></li><lidata-nav-id=/blog/post-00005/title="Strolch Release 1.0.0"class=dd-item><ahref=/blog/post-00005/>Strolch Release 1.0.0</a></li><lidata-nav-id=/blog/post-00004/title="DurationParameter and other minor changes: Release 1.0.0-RC4"class=dd-item><ahref=/blog/post-00004/>DurationParameter and other minor changes: Release 1.0.0-RC4</a></li><lidata-nav-id=/blog/post-00003/title="DB Initialization: Release 1.0.0-RC3"class=dd-item><ahref=/blog/post-00003/>DB Initialization: Release 1.0.0-RC3</a></li><lidata-nav-id=/blog/post-00002/title="Release 1.0.0-RC2"class=dd-item><ahref=/blog/post-00002/>Release 1.0.0-RC2</a></li><lidata-nav-id=/blog/post-00001/title="Release 1.0.0-RC1"class=dd-item><ahref=/blog/post-00
for them. The API will be as follows:</p><divclass=highlight><prestyle=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><codeclass=language-textdata-lang=text>GET ../rest/books?query=,offset=,limit=
GET ../rest/books/{id}
POST ../rest/books
PUT ../rest/books/{id}
DELETE ../rest/books/{id}
</code></pre></div><p>Thus corresponding with querying, getting, creating, updating and removing of
books. So let’s go ahead and add these REST APIs to our project.</p><p>Our project is using JAX-RS 2.0 as the API and Jersey 2.x as the implementation,
thus first we need to configure JAX-RS. Thus create the following class:</p><divclass=highlight><prestyle=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><codeclass=language-javadata-lang=java><spanstyle=color:#a6e22e>@ApplicationPath</span><spanstyle=color:#f92672>(</span><spanstyle=color:#e6db74>"rest"</span><spanstyle=color:#f92672>)</span>
</code></pre></div><p>As we add new resources they will be automatically since we register the entire package.</p><p>Now add the books resource class:</p><divclass=highlight><prestyle=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><codeclass=language-javadata-lang=java><spanstyle=color:#a6e22e>@Path</span><spanstyle=color:#f92672>(</span><spanstyle=color:#e6db74>"books"</span><spanstyle=color:#f92672>)</span>
</code></pre></div><h2id=search>Search</h2><p>The first service we’ll add is to query, or search for the existing books. The
API defines three parameters, with which the result can be controlled. The
method can be defined as follows:</p><divclass=highlight><prestyle=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><codeclass=language-javadata-lang=java>
</code></pre></div><p>To fill this method we need a few things. First let’s define a constants class where we keep String constants which we used in the model file:</p><divclass=highlight><prestyle=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><codeclass=language-javadata-lang=java><spanstyle=color:#66d9ef>public</span><spanstyle=color:#66d9ef>class</span><spanstyle=color:#a6e22e>BookShopConstants</span><spanstyle=color:#f92672>{</span>
</code></pre></div><p>As this tutorial progresses, more and more constants will be added here. This
class helps with two issues: Through the constants we can easily reason over
where certain fields, and types are used and of course String literals in code
are a rather bad thing.</p><p>In Strolch there are multiple way to access objects. The old way was using
Queries, the new search API is much more fluent and easier to read and write.
The search API, as well as the deprecated query API allows us to implement
privilege validation and thus one should create corresponding classes for each
type of search. Book entities are Resources, thus we will be creating a
<code>ResourceSearch</code>. The search is for Resources of type Book thus the resulting
search looks as follows:</p><divclass=highlight><prestyle=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><codeclass=language-javadata-lang=java><spanstyle=color:#66d9ef>public</span><spanstyle=color:#66d9ef>class</span><spanstyle=color:#a6e22e>BooksSearch</span><spanstyle=color:#f92672><</span>U<spanstyle=color:#f92672>></span><spanstyle=color:#66d9ef>extends</span> ResourceSearch<spanstyle=color:#f92672><</span>U<spanstyle=color:#f92672>></span><spanstyle=color:#f92672>{</span>
</span><spanstyle=color:#75715e></span> value <spanstyle=color:#f92672>=</span> value<spanstyle=color:#f92672>.</span><spanstyle=color:#a6e22e>trim</span><spanstyle=color:#f92672>();</span>
</code></pre></div><p>Note how we added a special <code>stringQuery(String)</code>-method. This method defines
where a search string entered by the user will be used to match a book. In this
case for <code>id</code>, <code>name</code> and the <code>description</code> parameter.</p><p>So that our users can call this query, we must give them this as a privilege.
This is done by adding the full class name to the <code>PrivilegeRoles.xml</code> file as
</code></pre></div><divclass="notices tip"><p>Note: The <code>internal</code> allow value is a special privilege which
is used internally when a service or something performs internal queries. This
means that a service can perform a query for object to which the user might not
have access, but without which the service could not be completed. We will use
this in a later stage.</p></div><p>Now we have all parts we need to implement the query method. The method will
include opening a transaction, instantiating the search, executing the search,
and returning the result:</p><divclass=highlight><prestyle=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><codeclass=language-javadata-lang=java>
<spanstyle=color:#66d9ef>return</span> ResponseUtil<spanstyle=color:#f92672>.</span><spanstyle=color:#a6e22e>toResponse</span><spanstyle=color:#f92672>(</span>paging<spanstyle=color:#f92672>,</span> e <spanstyle=color:#f92672>-></span> e<spanstyle=color:#f92672>.</span><spanstyle=color:#a6e22e>accept</span><spanstyle=color:#f92672>(</span>visitor<spanstyle=color:#f92672>));</span>
<spanstyle=color:#f92672>}</span>
<spanstyle=color:#f92672>}</span>
</code></pre></div><divclass="notices tip"><p>Note: We automatically transform the Resource objects to JSON
using the <code>StrolchElementToJsonVisitor</code>. By calling the method <code>.flat()</code>-method we have a
more compact JSON format. Paging is handled by a util class.</p></div><p>The helper class <code>ResponseUtil</code> takes care of creating the <code>JsonObject</code> and the
proper page. As a rule we use the format where we return two fields: <code>msg</code> is a
dash if all is ok, otherwise an error message will be present. Data is always in
the <code>data</code> field. This is just a personal taste, and can be changed to one’s own
taste.</p><h2id=get>Get</h2><p>We have all we need now to implement the GET method:</p><divclass=highlight><prestyle=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><codeclass=language-javadata-lang=java><spanstyle=color:#a6e22e>@GET</span>
<spanstyle=color:#66d9ef>return</span> ResponseUtil<spanstyle=color:#f92672>.</span><spanstyle=color:#a6e22e>toResponse</span><spanstyle=color:#f92672>(</span>Status<spanstyle=color:#f92672>.</span><spanstyle=color:#a6e22e>NOT_FOUND</span><spanstyle=color:#f92672>,</span><spanstyle=color:#e6db74>"Book "</span><spanstyle=color:#f92672>+</span> id <spanstyle=color:#f92672>+</span><spanstyle=color:#e6db74>" does not exist!"</span><spanstyle=color:#f92672>);</span>
</code></pre></div><divclass="notices tip"><p>Note how we simply retrieve the book as a Resource from the
TX. This is a good moment to familiarize yourself with the API of the
<code>StrolchTransaction</code>. There are methods to retrieve elements, and also perform
searches. We will use more of these methods later.</p></div><p>Further it can be noted that a simple retrieval isn’t validated against the
user’s privileges, the user is authenticated, which is enough for the moment.</p><h2id=create>Create</h2><p>To create a new book we need to implement a <code>Service</code>. This service will be called
<code>CreateBookService</code>. A Service always has a <code>ServiceArgument</code> and a <code>ServiceResult</code>.
Our service will use the <code>JsonServiceArgument</code> and the <code>JsonServiceResult</code>. The
implementation of the POST method is as follows:</p><divclass=highlight><prestyle=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><codeclass=language-javadata-lang=java><spanstyle=color:#a6e22e>@POST</span>
</code></pre></div><divclass="notices tip"><p>Note: We return the created object again as JSON in its own data field.</p></div><p>The service is implemented as follows:</p><divclass=highlight><prestyle=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><codeclass=language-javadata-lang=java><spanstyle=color:#66d9ef>public</span><spanstyle=color:#66d9ef>class</span><spanstyle=color:#a6e22e>CreateBookService</span><spanstyle=color:#66d9ef>extends</span> AbstractService<spanstyle=color:#f92672><</span>JsonServiceArgument<spanstyle=color:#f92672>,</span> JsonServiceResult<spanstyle=color:#f92672>></span><spanstyle=color:#f92672>{</span>
<spanstyle=color:#75715e>// get a new book "instance" from the template
</span><spanstyle=color:#75715e></span> book <spanstyle=color:#f92672>=</span> tx<spanstyle=color:#f92672>.</span><spanstyle=color:#a6e22e>getResourceTemplate</span><spanstyle=color:#f92672>(</span>BookShopConstants<spanstyle=color:#f92672>.</span><spanstyle=color:#a6e22e>TYPE_BOOK</span><spanstyle=color:#f92672>);</span>
<spanstyle=color:#75715e>// map all values from the JSON object into the new book element
</code></pre></div><divclass="notices tip"><p>Note: For the authenticated user to be able to perform this service, we must add it to their privileges:</p></div><divclass=highlight><prestyle=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><codeclass=language-xmldata-lang=xml>...
</code></pre></div><h2id=update>Update</h2><p>Updating of a book is basically the same as the creation, we just use PUT,
verify that the book exists and give the user the privilege.</p><p><strong>PUT Method:</strong></p><divclass=highlight><prestyle=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><codeclass=language-javadata-lang=java><spanstyle=color:#a6e22e>@PUT</span>
</span><spanstyle=color:#75715e></span> DBC<spanstyle=color:#f92672>.</span><spanstyle=color:#a6e22e>PRE</span><spanstyle=color:#f92672>.</span><spanstyle=color:#a6e22e>assertEquals</span><spanstyle=color:#f92672>(</span><spanstyle=color:#e6db74>"ObjectId and given Id must be same!"</span><spanstyle=color:#f92672>,</span> arg<spanstyle=color:#f92672>.</span><spanstyle=color:#a6e22e>objectId</span><spanstyle=color:#f92672>,</span>
</span><spanstyle=color:#75715e></span> book <spanstyle=color:#f92672>=</span> tx<spanstyle=color:#f92672>.</span><spanstyle=color:#a6e22e>getResourceBy</span><spanstyle=color:#f92672>(</span>BookShopConstants<spanstyle=color:#f92672>.</span><spanstyle=color:#a6e22e>TYPE_BOOK</span><spanstyle=color:#f92672>,</span> arg<spanstyle=color:#f92672>.</span><spanstyle=color:#a6e22e>objectId</span><spanstyle=color:#f92672>,</span><spanstyle=color:#66d9ef>true</span><spanstyle=color:#f92672>);</span>
<spanstyle=color:#75715e>// map all values from the JSON object into the new book element
</code></pre></div><h2id=notes>Notes</h2><p>One should now see a pattern emerge:</p><ul><li>The REST API delegates to the Services, or Searches, with the exception of the
retrieval of a single object by id.</li><li>Services should do initial validation of the input. Not much validation was
done here, but more could be done.</li><li>Commands are reusable objects to perform recurring work.</li><li>Searches and Services are privileged actions for which a user must have the
privilege to perform the action.</li></ul><p>The book services are quite simple, but as more requirements arise, it should be
easy to implement them in the service layer. Thus should a service be required
to be performed by an integration layer, then they can simply call the services,
since the input is defined and validation is done there (i.e. NOT in the REST
API).</p><p>This concludes the CRUD of books.</p><footerclass=footline></footer></div></div><divid=navigation><aclass="nav nav-prev"href=/tutorial/model/title=Model><iclass="fa fa-chevron-left"></i></a><aclass="nav nav-next"href=/download/title=Downloadstyle=margin-right:0><iclass="fa fa-chevron-right"></i></a></div></section><divstyle=left:-1000px;overflow:scroll;position:absolute;top:-1000px;border:none;box-sizing:content-box;height:200px;margin:0;padding:0;width:200px><divstyle=border:none;box-sizing:content-box;height:200px;margin:0;padding:0;width:200px></div></div><scriptsrc=/js/clipboard.min.js?1678977092></script><scriptsrc=/js/perfect-scrollbar.min.js?1678977092></script><scriptsrc=/js/perfect-scrollbar.jquery.min.js?1678977092></script><scriptsrc=/js/jquery.sticky.js?1678977092></script><scriptsrc=/js/featherlight.min.js?1678977092></script><scriptsrc=/js/highlight.pack.js?1678977092></script><script>hljs.initHighlightingOnLoad();</script><scriptsrc=/js/modernizr.custom-3.6.0.js?1678977092></script><scriptsrc=/js/learn.js?1678977092></script><scriptsrc=/js/hugo-learn.js?1678977092></script><scriptsrc=/mermaid/mermaid.js?1678977092></script><script>mermaid.initialize({startOnLoad:true});</script><scripttype=text/javascript>var_paq=window._paq=window._paq||[];_paq.push(["setDocumentTitle",document.domain+"/"+document.title]);_paq.push(["setCookieDomain","*.strolch.li"]);_paq.push(['trackPageView']);_paq.push(['enableLinkTracking']);(function(){varu="https://piwik.eitchnet.ch/";_paq.push(['setTrackerUrl',u+'matomo.php']);_paq.push(['setSiteId','2']);vard=document,g=d.createElement('script'),s=d.getElementsByTagName('script')[0];g.type='text/javascript';g.async=true;g.src=u+'matomo.js';s.parentNode.insertBefore(g,s);})();</script></body></html>