X-Git-Url: http://pere.pagekite.me/gitweb/homepage.git/blobdiff_plain/f56075a324a9214ef931aaaf79af60faa6decde7..649c043f27d3acfaa76450b8c04c230a9d20e9d1:/blog/archive/2019/03/03.rss diff --git a/blog/archive/2019/03/03.rss b/blog/archive/2019/03/03.rss index 7415f50f6c..56da5b63ce 100644 --- a/blog/archive/2019/03/03.rss +++ b/blog/archive/2019/03/03.rss @@ -6,6 +6,207 @@ http://people.skolelinux.org/pere/blog/ + + PlantUML for text based UML diagram modelling - nice free software + http://people.skolelinux.org/pere/blog/PlantUML_for_text_based_UML_diagram_modelling___nice_free_software.html + http://people.skolelinux.org/pere/blog/PlantUML_for_text_based_UML_diagram_modelling___nice_free_software.html + Mon, 25 Mar 2019 09:35:00 +0100 + <p>As part of my involvement with the +<a href="https://gitlab.com/OsloMet-ABI/nikita-noark5-core/">Nikita +Noark 5 core project</a>, I have been proposing improvements to the +API specification created by <a href="https://www.arkivverket.no/">The +National Archives of Norway</a> and helped migrating the text from a +version control system unfriendly binary format (docx) to Markdown in +git. Combined with the migration to a public git repository (on +github), this has made it possible for anyone to suggest improvement +to the text.</p> + +<p>The specification is filled with UML diagrams. I believe the +original diagrams were modelled using Sparx Systems Enterprise +Architect, and exported as EMF files for import into docx. This +approach make it very hard to track changes using a version control +system. To improve the situation I have been looking for a good text +based UML format with associated command line free software tools on +Linux and Windows, to allow anyone to send in corrections to the UML +diagrams in the specification. The tool must be text based to work +with git, and command line to be able to run it automatically to +generate the diagram images. Finally, it must be free software to +allow anyone, even those that can not accept a non-free software +license, to contribute.</p> + +<p>I did not know much about free software UML modelling tools when I +started. I have used dia and inkscape for simple modelling in the +past, but neither are available on Windows, as far as I could tell. I +came across a nice +<a href="https://modeling-languages.com/text-uml-tools-complete-list/">list +of text mode uml tools</a>, and tested out a few of the tools listed +there. <a href="http://plantuml.com/">The PlantUML tool</a> seemed +most promising. After verifying that the packages +<a href="https://tracker.debian.org/pkg/plantuml">is available in +Debian</a> and found <a href="https://github.com/plantuml/plantuml">its +Java source</a> under a GPL license on github, I set out to test if it +could represent the diagrams we needed, ie the ones currently in +<a href="https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/">the +Noark 5 Tjenestegrensesnitt specification</a>. I am happy to report +that it could represent them, even thought it have a few warts here +and there.</p> + +<p>After a few days of modelling I completed the task this weekend. A +temporary link to the complete set of diagrams (original and from +PlantUML) is available in +<a href="https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/issues/76">the +github issue discussing the need for a text based UML format</a>, but +please note I lack a sensible tool to convert EMF files to PNGs, so +the "original" rendering is not as good as the original was in the +publised PDF.</p> + +<p>Here is an example UML diagram, showing the core classes for +keeping metadata about archived documents:</p> + +<pre> +@startuml +skinparam classAttributeIconSize 0 + +!include media/uml-class-arkivskaper.iuml +!include media/uml-class-arkiv.iuml +!include media/uml-class-klassifikasjonssystem.iuml +!include media/uml-class-klasse.iuml +!include media/uml-class-arkivdel.iuml +!include media/uml-class-mappe.iuml +!include media/uml-class-merknad.iuml +!include media/uml-class-registrering.iuml +!include media/uml-class-basisregistrering.iuml +!include media/uml-class-dokumentbeskrivelse.iuml +!include media/uml-class-dokumentobjekt.iuml +!include media/uml-class-konvertering.iuml +!include media/uml-datatype-elektronisksignatur.iuml + +Arkivstruktur.Arkivskaper "+arkivskaper 1..*" <-o "+arkiv 0..*" Arkivstruktur.Arkiv +Arkivstruktur.Arkiv o--> "+underarkiv 0..*" Arkivstruktur.Arkiv +Arkivstruktur.Arkiv "+arkiv 1" o--> "+arkivdel 0..*" Arkivstruktur.Arkivdel +Arkivstruktur.Klassifikasjonssystem "+klassifikasjonssystem [0..1]" <--o "+arkivdel 1..*" Arkivstruktur.Arkivdel +Arkivstruktur.Klassifikasjonssystem "+klassifikasjonssystem [0..1]" o--> "+klasse 0..*" Arkivstruktur.Klasse +Arkivstruktur.Arkivdel "+arkivdel 0..1" o--> "+mappe 0..*" Arkivstruktur.Mappe +Arkivstruktur.Arkivdel "+arkivdel 0..1" o--> "+registrering 0..*" Arkivstruktur.Registrering +Arkivstruktur.Klasse "+klasse 0..1" o--> "+mappe 0..*" Arkivstruktur.Mappe +Arkivstruktur.Klasse "+klasse 0..1" o--> "+registrering 0..*" Arkivstruktur.Registrering +Arkivstruktur.Mappe --> "+undermappe 0..*" Arkivstruktur.Mappe +Arkivstruktur.Mappe "+mappe 0..1" o--> "+registrering 0..*" Arkivstruktur.Registrering +Arkivstruktur.Merknad "+merknad 0..*" <--* Arkivstruktur.Mappe +Arkivstruktur.Merknad "+merknad 0..*" <--* Arkivstruktur.Dokumentbeskrivelse +Arkivstruktur.Basisregistrering -|> Arkivstruktur.Registrering +Arkivstruktur.Merknad "+merknad 0..*" <--* Arkivstruktur.Basisregistrering +Arkivstruktur.Registrering "+registrering 1..*" o--> "+dokumentbeskrivelse 0..*" Arkivstruktur.Dokumentbeskrivelse +Arkivstruktur.Dokumentbeskrivelse "+dokumentbeskrivelse 1" o-> "+dokumentobjekt 0..*" Arkivstruktur.Dokumentobjekt +Arkivstruktur.Dokumentobjekt *-> "+konvertering 0..*" Arkivstruktur.Konvertering +Arkivstruktur.ElektroniskSignatur -[hidden]-> Arkivstruktur.Dokumentobjekt +@enduml +</pre> + +<p><a href="http://plantuml.com/class-diagram">The format</a> is quite +compact, with little redundant information. The text expresses +entities and relations, and there is little layout related fluff. One +can reuse content by using include files, allowing for consistent +naming across several diagrams. The include files can be standalone +PlantUML too. Here is the content of +<tt>media/uml-class-arkivskaper.iuml<tt>:</p> + +<pre> +@startuml +class Arkivstruktur.Arkivskaper <Arkivenhet> { + +arkivskaperID : string + +arkivskaperNavn : string + +beskrivelse : string [0..1] +} +@enduml +</pre> + +<p>This is what the complete diagram for the PlantUML notation above +look like:</p> + +<p><img width="80%" src="http://people.skolelinux.org/pere/blog/images/2019-03-25-noark5-plantuml-diagrameksempel.png"></p> + +<p>A cool feature of PlantUML is that the generated PNG files include +the entire original source diagram as text. The source (with include +statements expanded) can be extracted using for example +<tt>exiftool</tt>. Another cool feature is that parts of the entities +can be hidden after inclusion. This allow to use include files with +all attributes listed, even for UML diagrams that should not list any +attributes.</p> + +<p>The diagram also show some of the warts. Some times the layout +engine place text labels on top of each other, and some times it place +the class boxes too close to each other, not leaving room for the +labels on the relationship arrows. The former can be worked around by +placing extra newlines in the labes (ie "\n"). I did not do it here +to be able to demonstrate the issue. I have not found a good way +around the latter, so I normally try to reduce the problem by changing +from vertical to horizontal links to improve the layout.</p> + +<p>All in all, I am quite happy with PlantUML, and very impressed with +how quickly its lead developer responds to questions. So far I got an +answer to my questions in a few hours when I send an email. I +definitely recommend looking at PlantUML if you need to make UML +diagrams. Note, PlantUML can draw a lot more than class relations. +Check out the documention for a complete list. :)</p> + +<p>As usual, if you use Bitcoin and want to show your support of my +activities, please send Bitcoin donations to my address +<b><a href="bitcoin:15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b">15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b</a></b>.</p> + + + + + Release 0.3 of free software archive API system Nikita announced + http://people.skolelinux.org/pere/blog/Release_0_3_of_free_software_archive_API_system_Nikita_announced.html + http://people.skolelinux.org/pere/blog/Release_0_3_of_free_software_archive_API_system_Nikita_announced.html + Sun, 24 Mar 2019 14:30:00 +0100 + <p>Yesterday, a new release of +<a href="https://gitlab.com/OsloMet-ABI/nikita-noark5-core/">Nikita +Noark 5 core project</a> was +<a href="https://lists.nuug.no/pipermail/nikita-noark/2019-March/000451.html">announced +on the project mailing list</a>. The free software solution is an +implementation of the Norwegian archive standard Noark 5 used by +government offices in Norway. These were the changes in version 0.3 +since version 0.2.1 (from NEWS.md):</p> + +<ul> + <li>Improved ClassificationSystem and Class behaviour.</li> + <li>Tidied up known inconsistencies between domain model and hateaos links.</li> + <li>Added experimental code for blockchain integration. </li> + <li>Make token expiry time configurable at upstart from properties file.</li> + <li>Continued work on OData search syntax.</li> + <li>Started work on pagination for entities, partly implemented for Saksmappe.</li> + <li>Finalise ClassifiedCode Metadata entity.</li> + <li>Implement mechanism to check if authentication token is still + valid. This allow the GUI to return a more sensible message to the + user if the token is expired.</li> + <li>Reintroduce browse.html page to allow user to browse JSON API using + hateoas links.</li> + <li>Fix bug in handling file/mappe sequence number. Year change was + not properly handled.</li> + <li>Update application yml files to be in sync with current development.</li> + <li>Stop 'converting' everything to PDF using libreoffice. Only + convert the file formats doc, ppt, xls, docx, pptx, xlsx, odt, odp + and ods.</li> + <li>Continued code style fixing, making code more readable.</li> + <li>Minor bug fixes.</li> + +</ul> + +<p>If free and open standardized archiving API sound interesting to +you, please contact us on IRC +(<a href="irc://irc.freenode.net/%23nikita">#nikita on +irc.freenode.net</a>) or email +(<a href="https://lists.nuug.no/mailman/listinfo/nikita-noark">nikita-noark +mailing list</a>).</p> + +<p>As usual, if you use Bitcoin and want to show your support of my +activities, please send Bitcoin donations to my address +<b><a href="bitcoin:15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b">15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b</a></b>.</p> + + + Åpen og gjennomsiktig vedlikehold av spesifikasjonen for Noark 5 Tjenestegrensesnitt http://people.skolelinux.org/pere/blog/_pen_og_gjennomsiktig_vedlikehold_av_spesifikasjonen_for_Noark_5_Tjenestegrensesnitt.html