DEV Community: Elmar Dott

Java Enterprise in briefly detail

Elmar Dott — Fri, 15 Apr 2022 18:10:56 +0000

May you are a bit reserved to start with Java EE, because it looks so confusion. But don't worry it's not so difficult like it seems in the beginning.

As first is important to understand the game of the name. Since Java EE8 the eclipse foundation took the ownership from Oracle maintenance the Java Enterprise Platform. The eclipse foundation and Oracle was not able to find a common agreement for the usage of the Java Trademark. As solution Java EE was renamed to Jakarta EE.

Another fact we need to keep in mind is that Java EE is a collection of specifications. The reference implementation of those specifications is a bundle called application server. If you plan a small project just using the Servlet specification, you don't need to deal with a full application server. A simple Servlet container like Tomcat or Jetty contains everything you need.

Now comes the tricky part. to run a application server or a Servlet container you need a Java Virtual Machine (JVM). The version of the JVM must fit with the specification need of you application server. You need also to check which J EE version is supported by your application server. To stay a bit secure, without updating your environment every 6 months you can use the Java LTS release. Java 11 will have support until 2021 and Java 17 (LTS) released in September 2021 will have for 3 years support until 2024.

If you searching for an compact overview of the Jakarta EE Specification details you can check out my blog post: Java Enterprise in briefly detail

If you like my work, feel free to give a like and share with you friends and / or colleges.

Pull or not to pull

Elmar Dott — Mon, 03 Jan 2022 22:05:19 +0000

Pull requests like they are known from GitHub gets more and more popular in enterprise software development. This workflow also known as dictatorship or with his adaption to dictator-lieutenant, is a well proven process for open source projects. But in my perception - I always ask my self: We do really want this in commercial projects? I don’t think so. Because we already had in the past a tool called IBM Synergy with an equal approach. It was very heavy weighted and companies who used Synergy was looking quite fast to replace the software for better solutions.

Well, pull request now integrated into close to every DevOps tool, for Example Microsoft Azure and so on. Of course they absolutely more light weighted than the IMB Synergy workflow. But there is a big misunderstanding in commercial projects. Tools like Git, Subversion or Bazaar are just a storage for developer collaboration. Not a quality gate. The reason is quit easy explained.

A build manager is usually not be able to decide if a implementation fits well to the architecture. This are tasks for an Architect. In my humble opinion, I think a better and less time consuming strategy in enterprise projects, are code reviews shortly before a sprint is closed or directly after the sprint. Then, all the code is integrated and the metric tools deliver better results on test coverage, code smells and code duplication. Pull requests stresses developers more than they increase their implementation skills.

Before you start a lot of activities in the hope as overall result you project reach a better quality, you should wait and think twice. Don't run - take a breath and think about what you really wish to make better in your project. There many aspects about quality. B. W. Boehm published in 1975 a research paper how to define quality and how it can measured. May you want to have a look on my DZone article about software quality.

If you have the idea to use pull request to secure the quality for your off shore vendor team, you might be wrong. You should select well educated developers for a higher price, which delivers better code because of their experience. There is a great book about how to work together with off shore development teams, written from Nick Krym “Outsource It!”. [2012, The Pragmatic Programmers, ISBN-13: 978-1-93778-505-5]

The meaning of version numbers

Elmar Dott — Tue, 11 Feb 2020 16:18:40 +0000

When we exploring projects on GitHub, many times you can find the version number of artifacts like 0.9 or similar to that. Also very popular Frameworks like Spring mark their Artifacts with a label for example 5.1.2.Release. Sometimes appearing patterns like 3.0.0-alpha or 3.0.0-beta. Of course you can choose every pattern you like, to mark a special status of your application or library. But if you think twice about it, you may will realize this is not a recommendable practice.

By personal experience, I would always recommend to follow the semantic versioning (https://semver.org) approach. Semantic Versioning is an unofficial standard and with his short rule set easy to learn and use. But before I explain all the benefits you will win with this way of setting your version numbers, let me show how easy it works.

• Major: incompatible API changes
• Minor: add/ update functionality
• Patch: BugFixes
• Label: SNAPSHOT – to mark the under development status

With this simple overview, you already have everything you need to start with semantic versioning. Let’s have a bit deeper insight to these points and for what they stands for in the context of source code.

I. An incompatible API change means that a method you already have in your code base is removed or the signature is changed. In those cases the MAJOR part of the version number have to increase.
II. As long only new classes or methods are added, we did not infect to the usage of the previous work. This scenarios usually describe adding new functionality. In this context we increment the MINOR version number.
III. At least, when a bug is fixed we need to deliver the corrections in an own release and we have to increment the PATCH level. This changes don’t include feature updates or something other than the correction.
IV. During the implementation the version number is labeled with SNAPSHOT.

This simple rule set allows you an easy setup of you git branches, because in general you work in the master or develop branch. Only in the case of a fix for an already deployed release, we go back to the revision is marked with the release tag and create a bug fix branch. In this branch we only perform the fix and prepare a new release after everything is well. In this point you don’t effect any other work, because you are isolated. You can not bring in that way by accident new and untested functionality to the correction. After the correction is done, easily you can merge the bug fix branch to the master without having any conflict.

In my perception a version number less than 1.0 or labels like alpha suggest an incomplete or not well developed artifact. As consequence I try to avoid the usage of such marked releases. When I start with a new project I always start with 1.0-SNAPSHOT as first version number. Only when the minimal functionality is implemented, that the artifact is usable, then and only then I prepare the first release 1.0 and publish the binary. If after that an heavy bug is detected I perform a correction and publish the fixed artifact under 1.0.1 version number. In between I work on version 1.1-SNAPSHOT till I have the new functionality in a status is working well.

Always when I see a new major release of a library I use, I check as first if there some incompatibilities to my project. Then I can decide if I want to update my project to this newer version. Sometimes its to much work and you need to shift an update to a time when you have enough resources to do the migration well. Not every Major release brings feal benefits to your own project. The idea of “Always latest is greatest.” is not that good advice like it sometimes seems.

The meaning of package.htm vs. package-info.java

Elmar Dott — Fri, 31 Jan 2020 02:30:26 +0000

If you browse through Java projects in GitHub you find often files named package.html with content like:

<HTML>
    <BODY>
        Utils: Helpful things, which shouldn't implement against an Interface.
        <p>
            @since 1.0
    </BODY>
</HTML>

The meaning is very clear. This file describes which type of Java classes should placed there. The syntax allows several Annotations to extend the information. Another nice effect, mostly developers not aware about it, is the usage as placeholder. Let me fast explain what I mean with it. Of course we are in the context of java development and in the moment you start your project, you have to create the directory structure. When you use a build tool like Maven, you could start your project with running an archetype to do the job. If you use the common IDEs like NetBeans you can choose from plenty templates. After this step is follows mostly a fist commit to a Source Control Management system (SCM) like git or Subversion. But there is a small problem. Git don’t let you commit empty directories. As solution many developers create hidden files named .keept. This practice is common and well established, but when you create empty packages and place instead your package.htm you solve two problems. As first Git let you commit your directory and you already include a documentation for developers which content is expected in this package.

Less common are package-info.java files, introduced in Java 5. The purpose of this files is equal to package.htm – it’s just a newer approach and the official recommendation from oracle to describe a package. Some developers have the idea using a java file for API documentation is an abuse, because they don’t contain code. The big different are the package annotations, you can use. Another argument is since Java 9 and the project Jigsaw for modularization is introduced a module-info.java file, located in the root of your project. This file is a descriptor of the whole module. There are defined used dependencies, accessible packages and other things. In my opinion is a good style to not mix up things and use as descriptor the java files. I believe the new approach brings more flexibility. For example you can place in the package-info.java compile time annotations, instead into the classes. This centralization avoid missing annotaions and reduce duplication's.

If your project contain both package.html and package-info.java, the prefferd source for JavaDoc will be always package-info.java. If you want to create the package-info.java file in Eclipse IDE by using a standard class, you will fail, because of the Java convention. To solve the problem, you just need to got to the package where you want to place your info file and create a new package. This package you can name as package-info.java.

Commit messages for source control management systems

Elmar Dott — Sun, 12 Jan 2020 20:31:41 +0000

Expressions for communication

Source control management systems (SCM) like Git or Subversion are standard tools for developers. Plenty tutorials spread around in the world wide web how to interact with this technology. But mostly a simple detail got not that much attention, like it should. It's how to write a proper commit message. In this short Blog we discuss why those messages have importance, not only in enterprise projects.

A typical practice are description about code changes like "update build script" or "fix tests". For other persons it is very difficult to catch what exactly was the purpose for the update or change. After a short time is passing, even the original author could not remind as well his activities. This means persons who need to investigate which revision contain a specific change need more time to detect, when the description of s revision is to general. This fact got more importance for collaborative teams using pull requests. For the one who need to decide if a request is accepted or refused, it's very important to figure quit fast out, which decision it should taken. In the next paragraphs we got introduced a new technique about writing very efficient commit messages, everybody can understand quickly. The following graphic is a short overview about a defined vocabulary for writing efficient commit messages.

The concept is quite simple and contains tree sections / lines. The identifier is independent and could be something like a feature ID. This ID is not related to any issue management system. Connecting tools like JIRA or Bugzilla you can use the optional section two with the descriptor. Not all projects connected with issue management systems, for that reason this entry is optional. In section tree you are able to give a more detailed information about the revision, enclosed in brackets. A full detail description you find in the paper on Research Gate. As you can see the usage is very simple and easy to extend or adapt. A small example shows you very fast the concept.

[CM-0500] #CHANGE ’function:pom’

{Change version number of the dependency JUnit from 4 to 5.0.2}

Here we see very special feature id. The intention to change a dependency in the build logic can obviously not related to a implemented feature. This is why general task are defined. Those task have the prefix CM and means configuration management. Here is a list of such task we already detect:

[CM-000] INIT
[CM-010] REVIEW
[CM-020] BRANCH
[CM-030] MERGE
[CM-040] RELEASE
[CM-050] build management

Much more real world examples you find in the GitHub project TP-CORE.

Vocabulary Description

#INIT – the repository or a release.
    repro:documentation / configuration …
    archetype:jar / war / ear / pom / zip …
    version:version
#IMPLEMENT – a functionality.
    function:clazz
#CHANGE – a functionality.
    function:clazz
#EXTEND – a functionality.
    function:clazz
    attach:clazz
#BUGFIX – a functionality.
    priority:critical / medium / low / design
#REVIEW – an implementation.
    refactor:function
    analyze:quality
    migrate:function
    format:source
#RELEASE – an artifact.
    version:version
#REVERT – a commit.
    commit:id
#BRANCH – create.
    create:name
    stash:branch
#MERGE – from another branch.
    from:branch
    to:branch
#CLOSE – a branch.
    branch:name

Resume
There some blog posts about the essence of well written informative commit messages for SCM. Every one who was needed to investigate inside a SCM for rollback of particular changes, know how helpful declarative comments are. But in the other hand, as developer we are not famous for our documentation skills. The proposed solution offer beside the already mentioned benefits another one. The commit messages are standardized and with this defined vocabulary it is possible to process them automatically to gather several project information.

Release cycles in agile projects

Elmar Dott — Mon, 06 Jan 2020 21:49:14 +0000

Agile project management techniques these days are not just common. They are essential for the software industry. In this context doesn’t matter if your project is driven by Scrum, Kanban or any other agile method. The main goal of a fast feedback for all of them is similar. It will help to reduce the risk of keep going whit something the client don’t want. This means the project have to delivered quit often - with a defined functionality set for the test and feedback cycle. In this way you are be able to detect problems very early, before a lot of time and money is wasted.

Here is a brief overview what it means agile release cycle and how it could work in practise. For example after a two weeks sprint the project need to delivered into a test stage. If some functionalities are not finished, the sprint will not extended. The missing implementation just got skipped for the next sprint. And of course every delivery is a full release, with his own release version. No build numbers are required. This fact is important to distinguish the artifacts and enable a well working bugfix process including a less complex branch strategy for your SCM system.

In between all those activities you have to aware that not every release have to push into production. It could be useful to plan every 3 or 6 months a well defined roll out. Huge and difficult functions moved to the beginning of such a cycle. Then will be enough time to complete and reach a good quality. Around two sprints before the cycle for a production roll out, is also a good time to review architecture and implementation details. This will secure maintainability for the future.

This process also implies a strong deploy pipeline, otherwise it could bind a lot of human resources. Manual activities are also error prone. This is why they should avoided. Following this simple conventions is also more important when you work with offshore teams. This requires an experienced project manager. A good recommendation to the product owner. If your project manager say something like: I am not a technical person. Kick him out. He will not understand basic problems and drive the project to fail.