How To Build A Application With No Third-Party Code In Core

For the background, please read my other post first: it is called “Application And Service Containers” and it helps understanding the core idea in this post; maybe Java Enterprise Edition (J2EE / JEE) containers after all got something right… What was it then, you may ask? Well, at least the idea of separating your application and it’s core from any 3rd party libraries or frameworks. However, there was a problem present too: the container was always provided by the application server (AS). While coding I started to notice certain pattern which I found to be extremely useful.

So what I propose:

use Java SPI and Service Loader to avoid including 3rd party code directly in your application – keep your app core clean and tight!
your application should only contain method calls which use services which are integrated via SPI!
frameworks like Spring must be integrated so that the app depends on interfaces and use Dependency Injection to inject implementation
communication with other services must be abstracted too: for example the transport mechanism must not be exposed, and the application should consume them as method calls. See details below…

So what should be integrated services not visible directly core code:

events like message queues
client-server request-response communication e.g. HTTP rest
Remote Procedure Calls e.g. gRPC
SOAP
3rd party application service like SendGrid etc.
microservice integration with service meshes or event-bus’es
frameworks or libraries like Spring or Guava

This should be possible to handle both synchronous and async cases, but you should understand that this approach might be too tedious and sometimes even impossible if you try to hide all libraries that you use. You should always decide and consider possible trade-offs before getting yourself into trouble…

IMO, traditional web containers and application containers are anti-patterns! So when building an application you should really start with standalone executable with NO containers whatsoever! For example, you can have a standalone executable JAR that consists of minimal Spring Framework dependencies! On top of that, you can use GraalVM to build native executables! No more embedded web servers like in Spring Boot, no more application servers like Tomcat, no more EAR/WAR deployments! Please, read more from http://zetcode.com/articles/standalonespring/.

P.S. Minimum required Spring modules for the impatient:
1. spring-core
2. spring-beans
3. spring-context

Application And Service Containers

Want to know how to implement Clean architecture in a modern and practical way? If yes, please read on… Do you remember when Java Application Servers (AS) were hip and cool? Or does J2EE, JEE, or Jakarta EE ring a bell? I will shortly recap the fundamental design of them. Java application servers had it almost right… They provided container where certain usually standardized configured services were available for Java applications. In the first image, please note “services”, and in the second please spot the “containers”. I will refer to them later on. For a long time these services and containers were the main way to build and deploy enterprise and web applications. And with certain modification these concepts turn easily into a concept of a modern backend behind an API.

JavaEE Application Server — JavaEE Application server (source: protechtraining.com)

But the world changed: developers started to consider that the enteprise application development was slow and cumbersome. For example, when you made a code change, you needed to compile code, run unit tests, build packages like JAR, WAR, and EAR, and finally do the deploy to a AS… During development each deployment might take several minutes. And most of the time you didn’t even need to use all available services. And often they didn’t fit in your requirements. ASs are still heavily used but the nowadays more lightweights solutions have emerged. Microservice thinking is now the new mainline. Btw, it is funny that many developers think that you can’t use AS as the base for a micro service. So in Java world there are now lots of (opionated) micro frameworks which try to be more aligned with the modern requirements. But even for microservices certain problems and de facto solutions started to appear. One of the most discussed thing is how you should integrate all the services together. The current solution is to use a message hub to send messages between services. Some don’t believe this and have started to cut down number of services and ultimately heading back to monolith/modulith direction – the worst is to have a distributed monolith!

So my idea is to bring back the container and service -thinking with a twist: the old JEE application container should be repurposed into (microservice) integration layer where the services are in fact your or 3rd party services. This allows an alternative solution to micro service integration. The other part in my idea is to have a application container where all the needed application components like persistence, caching, etc are taken into use and configured. This allows the application itself to focus only on capturing and implementing the (domain) business logic: please check this post for understanding how the application itself can be composed into layers. But note that application container and application are not really independent layers, but rather separate parts. The last layer is about data. Data is the most important thing – it is the “logic at-rest”! It should not have any dependencies but everything else should depend on it. Hmm, this starts to resemble Uncle Bob’s Clean architecture, right? See my own picture at the bottom of the page!

Clean Architecture — From [https://8thlight.com/blog/uncle-bob/2012/08/13/the-clean-architecture.html]

In my design Entities and Data are pretty much the same thing. However, Bob’s red and green circles correspond to my Application layer. Clean architecture does not have explicit circle for application base structure mainly because I don’t copy Bob’s work although they might be similar. Maybe the most unclear concept is the “new service container”. Let me elaborate. For example, let’s assume that your app sends emails via SendGrid’s service. This 3rd party service provides a Java library/client to send emails programmatically from the code. The downside is that you need to add the dependency and after that you code base shows 3rd party code there – at minimum in the imports. On the other hand if you choose to send API calls from the code you end up adding a sort of your own client, which is not good either. What can you do?

The service container is what could integrate your app to the external services. In the given example, your app uses a transparent service to send emails. So it is a service that you can add to you server. Of course you need to expose an interface for communication but it is quite close to wrapping external libraries with your own class. And there is already one possible way of doing this: you can create create extensible applications using Service provider interface (SPI)! I remember Uncle Bob speaking about how good plugins are, and SPIs are how you do them in Java. And funny enough, already J2EE services had JavaMail for sending emails! In fact it is still there in modern breed of application servers. To see how to use a service to send mail using a JEE service check out this JBoss documentation. In short,

// mapped resource and a wrapping object/interface
@Resource(mappedName="java:jboss/mail/Default")
private Session mailSession;

To conclude, here a picture of what I came up:

Use service container to integrate different services together: independent from the application
Use application container (compile-time) to configure technical base for application. Separate part of the application. It provides implementation for the constructs that the application uses e.g. “MyCacheImplementation”
Application depends on application container implementations and data, and it implements core business logic. For example, when developing the app you can use “MyCache” interface and later decide how the container fulfills that contract!
Data is solely about data: types, value, and metadata

IMO, traditional Java EE web containers and application containers are anti-patterns! My application containers are different as they are “thin” and programmatic containers! So when building an application you should really start with standalone executable with NO containers whatsoever! For example, you can have a standalone executable JAR that consists of minimal Spring Framework dependencies! On top of that, you can use GraalVM to build native executables! No more embedded web servers like in Spring Boot, no more application servers like Tomcat, no more EAR/WAR deployments! Please, read more from http://zetcode.com/articles/standalonespring/. The benefit from this is that you can integrate message queues – or even the web container functionality – as a service…

Summarized: Accessibility A11Y (For Developers)

Accessibility means web accessibility in this post. What is it? Let me start by a brief motivation: why should you care? First, for human reasons most importantly. From WCAG: “Web Content Accessibility Guidelines (WCAG) 2.1 covers a wide range of recommendations for making Web content more accessible. Following these guidelines will make content more accessible to a wider range of people with disabilities, including accommodations for blindness and low vision, deafness and hearing loss, limited movement, speech disabilities, photosensitivity, and combinations of these, and some accommodation for learning disabilities and cognitive limitations; but will not address every user need for people with these disabilities”. Second, it improves user experience (UX) for all. And third, there are regulatory reasons for this too: in EU there is the Web accessibility directive and in US there is a similar law called ADA. However, the laws currently don’t affect most of the private companies, but it might change in near future.

So what is it? Web Content Accessibility Guidelines (WCAG) 2.1 improves especially technical accessibility in internet. It has “12-13 guidelines that are organized under 4 principles: perceivable, operable, understandable, and robust. For each guideline, there are testable success criteria, which are at three levels: A, AA, and AAA.” Usually the target level is AA that also includes level A (AAA remarking full accessibility)! There is a summary which gives you a quick glance to it, which helps you get the “big picture”: https://www.w3.org/WAI/standards-guidelines/wcag/glance/. There is also a checklist which help you with how to meet the WCAG requirements. There also tools which you can use to evaluate your web content accessibility. It might be worth noting that there are many consultancy companies which sell accessibility audit/workshops. Some examples of technical tools for evaluation:

Achecker tool checks single HTML pages for conformance with accessibility standards to ensure the content can be accessed by everyone. See the Handbook link to the upper right for more about the Web Accessibility Checker.
WAVE Web Accessibility Evaluation Tool: WAVE is a suite of evaluation tools that helps authors make their web content more accessible to individuals with disabilities. WAVE can identify many accessibility and Web Content Accessibility Guideline (WCAG) errors, but also facilitates human evaluation of web content.
Constrastschecker for checking accessible colour contrasts

You also need to have a public, regularly updated, accessibility statement on your website: see the template “ACCESSIBILITY STATEMENT“. In Finland, you can use a builder to create it for you. In short, the statement should include:

What parts of your web site are not accessible, and reasons why: is it work in progress, not under regulation/law, or an unreasonable burden for some (what) reason
Feedback mechanisms for users to report inaccessible content
Possibility to access your relevant information in accessible format
A link to the enforcement procedure

Do Immutable Server States Adhere To REST Design?

I am a firm believer in REST design, but about a week ago I noticed thinking, do immutable server-side states satisfy REST constraints? I dare to say that the following adheres to REST design, or do I? My understanding of the REST design is that it requires stateless servers, but then again I find it increasing the complexity of the code. Let me try to explain what I mean with an example.

Role-based authorization for business logic and resources. A client is responsible for keeping the session state. The client representing the user (or Subject) can have multiple roles, and each role is associated with a set of permissions. All (business) actions and resources require checking if a role has a permission to execute or access. What I suggest is that a session of a user (Subject) would be bound to a transparent authorization layer by introducing a delegating subject that just delegates business logic calls and resource access to a authorization (manager). This means that a server would in fact have multiple states but each state would appear immutable to each other. Also, all communication in the server should utilize immutable message: for instance, check out Akka.

At the moment I am writing a piece of software that aims (in the long run) to provide a micro service for web application authentication and authorization. The idea is to use Apache Shiro (Delegating Subject) on server-side and expose control with role-based access over a REST API. But what I think is missing from the REST design is the that (when you actually write code) you end up needing a mechanism to carry or piggyback information to the deep areas of your business logic. For example, a user-supplied locale information according to which messages are translated, or the current user role in the given example, are often required to be available. So the sessions are counted in as immutable server states, but there are other states too: but the actual client state must still be in the client!

To summarize, I think that stateless server requirement is actually a bit off. Instead, it would be beneficial to require:

Asynchronous processing (non-blocking, and no dependencies between requests)
Sessions are externally immutable, but internally mutable (provides a useful context)
Communication uses immutable message (in Akka: Actor send rule)

So what do you think? Dare I? Do you agree or disagree?

Correct Design of HTML5 Wizards and Form Inputs and Buttons

I have been trying a lot of different designs for form inputs but simply nothing seemed “to “work” visually… Finally searching for different design alternatives I ended up recommending the following. A form input should consist of three parts:

First part is an icon (e.g. font awesome icon), some text, or an image. If you click area of this part, it expands to cover the whole input: this “boolean switch” type of behavior allows, for instance, using it to show and to hide help instructions. Of course, doing it again (twice) means reset.
Second, i.e. middle part, always contains input from a user. If user has not entered anything, i.e. an empty input, the text should advise user about what data should be entered to this input (commonly known as watermark text). Side note: always keep whatever user has entered to it and don’t automatically change it: even if it is invalid content.
Third and last part should be an action element that allows interaction with user. Visually it can be an embedded button with some text, or text like asterisk ‘*’ indicating a required field, or green check icon for validated and approved content, or red cross icon for an invalid field value, or kind of a split button that reveals more options when user clicks it. So whatever is the last element it should offer a binding to events: whether it is submit button or something else, the idea is to respond to a user (inter)action. Interesting enough, this could be also a Drag-and-drop area for files!

About colors. There are at least four different use cases for both data and form elements:

normal color (default)
focus color (e.g. blue)
validated content color (green)
invalid content color (red)
submit button color (gray if disabled), when enabled other color with white text

Color coding for buttons:

disabled or passive (alpha layer)
enabled or active (normal color)
primary action (frequent user action)
secondary (n-ary action, for less frequent or less important actions
interaction (hover shows button is selected + pushing it down for action)

When value is invalid, where should an error message be displayed and how? First of, there should be a “grouping” message indicating overall result, e.g. an overall message for the user stating if anything went wrong. In addition detailed error messages should be displayed too: preferred style is inline messaging right next to an erroneous field. The field with an error will be marked with red border, perhaps light red background color and darker red text, and a cross-icon/image/text as the third part. A user sees this and when he/she clicks to this field to fix the error (onfocus event in field) an inline message is be shown to the user. The user sees both the input text and the error message at the same time, so that he/she can fix the error easily: user should receive either instructions how to fill field value correctly, indication of where the error is located, or both. The error message disappears (temporarily) when user stops editing the field. Another important aspect is a tool-tip. Using tool-tip text is highly recommended, because it can fit more text than any other place in your design.

Dialogs like Sign in, Sign out, Sign as, Sign up, etc. should be in fact Wizards (with Cancel and Finish buttons that might have different labels though). A good example is a sign in (login) dialog: login is actually a login wizard meaning that it should provide flow of Cancel-Next, Prev(ious)-Next, … , Prev-Finish action options: however, login like any wizard is just Cancel-Action flow that leads into Action outcome or result. Typically you would see some mistakes in this implementation like possibility to close the wizard dialog window, or having all the buttons Cancel, Prev, Next, and Submit/Finish/etc. at each wizard step/page (even if some of them are disabled at times). In summary, steps are:

Form request
- User fills in data over multiple steps
- Last step contains the Action button(s) for example “Finish” or “Submit”
- So for each step the buttons are
  - 1st: Cancel+Next
  - Nth: Previous+Next
  - Lst: Previous+Action
Form response
- Action in the last step resulted into outcome result: positive or negative one
- Result is a UI component that cannot be closed elsewhere but there is a rounded navigation button that by default closes the dialog
- So for the outcome result the buttons are
  - OK or CLOSE by default, which closes the dialog window

User should not be allowed to stop the flow prematurely, but rather, fast-forward to the end always, which in practice might be invisible to the user. To make it faster to complete the flow, i.e. skip unnecessary steps, (parent) wizards should have hierarchical/inner/nested (parent/child) wizards which just group and wrap data into logical parts. In addition, flows typically have visual indicator on both current phase and completion stage. In short and as a rule, correct wizard design is such that a wizard always has exactly one and same entry and also one and same exit point, and the flow itself should be considered as “atomic”.

Simplest wizard according to these rules is Cancel-Finish (in login “Finish” word is replaced with a word “Sign in”). Note that flow should be usually defined left-to-right meaning Cancel and Prev buttons are located left and Finish and Next buttons are located right. There are at least two types of wizards or flows: a wizard that allows you go backwards and forward, and a wizard that goes only forward. For example, a lost password recovery wizard should go only forward and therefore have only button sequence of (possibly multiple) Cancel-Next and Cancel-Finish, i.e. no back-navigation: logically this means that you will have to restart recovery flow if you stop it before you complete it.

signInPass Image 1
signinFail Image 2
A good example is a sign in (login) dialog: login is actually a login wizard meaning that it should provide flow of Cancel-Next, Prev(ious)-Next, … , Prev-Finish action options. Actually, only “Cancel” and “Sign in” buttons are needed in this simple flow! Also note that users should not be allowed to close dialog window, but use the “Cancel” button.

Beautiful isn’t it! Oh, and one last thing. As I wrote already, a dialog should almost always show the result or outcome of the executed operation: or non-existence of it too! For example, if a user selects a paint for his house and then buys it with “Buy” button, the operation is obviously also called “buy” and after the execution there should be feedback available: either user bought the paint or something went wrong and he did not get it. Note that this feedback is different from the input field feedback and it could be understood as “button feedback”.

P.S. If you are searching for a product for creating complex forms, there are two possibilities: Orbeon Forms (orbeon.com) or Form.io form (form.io) – there is also form.io and Camunda integration plugin!