https://lealceldeiro.com Latest content in Software Development: technical content, professional experiences, and more. en-us Mon, 18 May 2026 11:49:26 +0000 Mon, 18 May 2026 11:49:26 +0000 2880 JBake https://lealceldeiro.com/img/rss_thumbnail.png https://lealceldeiro.com 144 99 https://lealceldeiro.com/articles/2024/the-strategy-pattern-and-springboot.html Tue, 9 Jul 2024 00:00:00 +0000 articles/2024/the-strategy-pattern-and-springboot.html <div id="toc" class="toc"> <div id="toctitle">In this article</div> <ul class="sectlevel1"> <li><a href="#_the_strategy_pattern">The Strategy Pattern</a></li> <li><a href="#_whats_spring_boot">What’s Spring Boot</a></li> <li><a href="#_the_strategy_pattern_in_spring_boot">The Strategy pattern in Spring Boot</a> <ul class="sectlevel2"> <li><a href="#_interchangeable_beans">Interchangeable beans</a> <ul class="sectlevel3"> <li><a href="#_the_example_scenario">The example scenario</a></li> <li><a href="#_creating_the_application">Creating the application</a></li> <li><a href="#_the_endpoint_implementation">The endpoint implementation</a></li> <li><a href="#_the_first_email_sender">The first email sender</a></li> <li><a href="#_integrating_with_the_first_email_provider">Integrating with the first email provider</a></li> <li><a href="#_the_real_challenge">The real challenge</a></li> <li><a href="#_spring_profiles_to_the_rescue">Spring profiles to the rescue</a></li> </ul> </li> <li><a href="#_other_applications">Other applications</a></li> <li><a href="#_strategy_in_spring_boot_itself">Strategy in Spring Boot itself</a></li> </ul> </li> <li><a href="#_github_repository">GitHub repository</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>The strategy pattern is one of the well-known software design patterns described in the famous book "Design Patterns: Elements of Reusable Object-Oriented Software". Its usage in Spring Boot offers a clean way to encapsulate different algorithms and behaviors that makes our applications more maintainable, flexible, and composed of loosely coupled components. In this article we’ll explore what this pattern is about and how to use it effectively in Spring Boot.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_strategy_pattern">The Strategy Pattern</h2> <div class="sectionbody"> <div class="paragraph"> <p>In the words of the renowned authors, the intent of the "Strategy" pattern, also known as "Policy", is to:</p> </div> <div class="quoteblock"> <blockquote> <div class="paragraph"> <p>Define a family of algorithms, encapsulate each one, and make them interchangeable.</p> </div> <div class="paragraph"> <p>Strategy lets the algorithm vary independently from clients that use it.</p> </div> </blockquote> <div class="attribution"> — Design Patterns: Elements of Reusable Object-Oriented Software </div> </div> <div class="paragraph"> <p>What does this mean exactly?</p> </div> <div class="paragraph"> <p>In simple terms, this means that for a given task, code routine, procedure, any algorithm in general, we can have several different implementations. Now, we don’t need to expose <em>the how</em> to the clients that consume that algorithm. Notice, by clients I mean any code that calls the algorithm.</p> </div> <div class="paragraph"> <p>By following this approach, we ensure our logic is not exposed unnecessarily, and we can evolve it without breaking any client. This is one of the fundamentals of <a href="/articles/2024/java-oop-classes-and-objects.html#what-are-java-classes" target="_blank" rel="noopener">Object-Oriented Programming</a>.</p> </div> <div class="paragraph"> <p>For more details about this pattern, you can check my notes about it in this <a href="https://github.com/lealceldeiro/gems/tree/master/DesignPatternsElementsOfReusableObjectOrientesSoftware/Chapter05/Strategy">GitHub repository</a>, or you can read it directly from the mentioned book—this is the <a href="https://amzn.to/3RIAiAY" target="_blank" rel="noopener">Amazon link</a>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_whats_spring_boot">What’s Spring Boot</h2> <div class="sectionbody"> <div class="paragraph"> <p>It’s challenging to find a Java developer nowadays who doesn’t know what <a href="https://spring.io/projects/spring-boot" target="_blank" rel="noopener">Spring Boot</a> is. Nevertheless, I once didn’t know what it was either. So, let’s give it a brief intro.</p> </div> <div class="quoteblock"> <blockquote> <div class="paragraph"> <p>Spring Boot makes it easy to create stand-alone, production-grade Spring based Applications that you can "just run".</p> </div> <div class="paragraph"> <p>We [Spring Boot maintainers] take an opinionated view of the Spring platform and third-party libraries so you can get started with minimum fuss. Most Spring Boot applications need minimal Spring configuration.</p> </div> </blockquote> <div class="attribution"> — Spring Boot documentation </div> </div> <div class="paragraph"> <p>That quote is almost impossible to simplify further, but just to make sure new developers understand it, let’s put it another way:</p> </div> <div class="paragraph"> <p>Spring Boot builds on top of the Spring framework and its ecosystem as well as Java’s. It contains all the capabilities provided by Spring and, additionally, most of the boilerplate code and configuration needed to run a traditional Spring application.</p> </div> <div class="paragraph"> <p>This way we can use Spring and many other libraries in our projects without having to worry about all the XML configuration files and code required to only run the application (to later on start coding the business logic). Instead, with Spring Boot, we add its dependencies (Maven, Gradle, etc.), some <a href="https://github.com/spring-projects/spring-boot/blob/main/spring-boot-project/spring-boot-starters/README.adoc" target="_blank" rel="noopener">starters</a>, as needed, and we’re ready to go by focusing on our business logic.</p> </div> <div class="paragraph"> <p>For a more in-depth look at how Spring and Spring Boot work, I’d recommend visiting their official websites or reading <a href="https://amzn.to/3VHWA74" target="_blank" rel="noopener">Spring Boot 3 and Spring Framework 6</a>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_strategy_pattern_in_spring_boot">The Strategy pattern in Spring Boot</h2> <div class="sectionbody"> <div class="paragraph"> <p>It’s clear that the strategy pattern has many applications, and it’s not the intention of this article to go through all of them; instead I’ll talk about one I find very interesting while using Spring Boot.</p> </div> <div class="paragraph"> <p>I’m referring to the capability to declare several components that achieve the same task in different ways, and use the best fit for a particular task at runtime—​I’ll call it "Interchangeable beans".</p> </div> <div class="paragraph"> <p>To do that, let’s take an example scenario, so what we build here makes some sense.</p> </div> <div class="paragraph"> <p>The code repository is at the end of the article, so you can check it out locally.</p> </div> <div class="sect2"> <h3 id="_interchangeable_beans">Interchangeable beans</h3> <div class="sect3"> <h4 id="_the_example_scenario">The example scenario</h4> <div class="paragraph"> <p>The requirements are as follows:</p> </div> <div class="ulist"> <ul> <li> <p>Build a simple web endpoint that will accept a <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST" target="_blank" rel="noopener"><code>POST</code></a> payload and will email a recipient. The endpoint will receive in the payload the following attributes. To keep it simple, there will be no validations or security checks performed and only one recipient can be emailed.</p> <div class="olist loweralpha"> <ol class="loweralpha" type="a"> <li> <p><code>to</code> (string): recipient’s email address</p> </li> <li> <p><code>subject</code> (string): email subject</p> </li> <li> <p><code>body</code> (string): email body</p> </li> </ol> </div> </li> <li> <p>The application needs to be deployed in different organizations where the internal email provider can be different. The providers that we’ll support are: <a href="https://developers.mailersend.com/" target="_blank" rel="noopener">Mailersend</a>, <a href="https://www.twilio.com/en-us/sendgrid/email-api" target="_blank" rel="noopener">Twilio</a>, <a href="https://www.mailgun.com/products/send/email-api/" target="_blank" rel="noopener">Mailgun</a>, and <a href="https://www.mailjet.com/products/email-api/" target="_blank" rel="noopener">Mailjet</a>.</p> </li> </ul> </div> </div> <div class="sect3"> <h4 id="_creating_the_application">Creating the application</h4> <div class="sect4"> <h5 id="_project_boilerplate">Project boilerplate</h5> <div class="paragraph"> <p>The first thing we need to do is to create the boilerplate for our Spring Boot application. To do that, we can use many alternatives, being the <a href="https://start.spring.io/">Spring initializer</a> one of the most commonly used among the community. Alternatively, if you use <a href="https://www.jetbrains.com/idea/">IntelliJ IDEA</a> Ultimate, you can also create the project directly from its <a href="https://www.jetbrains.com/help/idea/spring-initializr-project-wizard.html">Spring Boot Project Wizard</a>. Regardless of which option you choose, the final result should be the same.</p> </div> <div class="paragraph"> <p>Here’s what it’d look like from IntelliJ IDEA:</p> </div> <div class="imageblock"> <div class="content"> <img src="images/07/spring-boot-idea-project-wizard.webp" alt="IntelliJ IDEA Spring Boot project wizard" width="650" height="650"> </div> </div> <div class="paragraph"> <p>After the project is created, it’ll look like this:</p> </div> <div class="imageblock"> <div class="content"> <img src="images/07/spring-boot-app-structure.webp" alt="Spring Boot app project structure" width="650" height="650"> </div> </div> </div> </div> <div class="sect3"> <h4 id="_the_endpoint_implementation">The endpoint implementation</h4> <div class="paragraph"> <p>That’s all the boilerplate code needed. Now let’s focus on our business logic.</p> </div> <div class="paragraph"> <p>The first thing we need to implement is the endpoint that accepts the request with the email information and sends it to the recipient.</p> </div> <div class="paragraph"> <p>This is going to be as simple as adding the <em>Spring Boot Web</em> starter. To do it, I’ll add the corresponding Maven dependency in the pom.xml file.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"> <dependencies> <!-- ... --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- ... --> </dependencies></code></pre> </div> </div> <div class="paragraph"> <p>Now we’re ready to add the controller class. It’s as simple as this:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@RestController("email") public class EmailController { @PostMapping("/send") public String sendEmail(@RequestBody EmailRequestDto body) { // TODO: actually send the email return "Email sent"; } }</code></pre> </div> </div> <div class="paragraph"> <p>And when we call the endpoint <code>email/send</code> it returns <code>Email sent</code>, as you can see in the image below.</p> </div> <div class="imageblock"> <div class="content"> <img src="images/07/spring-boot-controller-endpoint.webp" alt="Rest Controller" width="850" height="750"> </div> </div> <div class="paragraph"> <p>But so far, there’s no actual email being sent. It just returns that fancy message.</p> </div> </div> <div class="sect3"> <h4 id="_the_first_email_sender">The first email sender</h4> <div class="paragraph"> <p>Up to here this has been straightforward. Now comes the interesting part. We need to add a <em>component</em> that does the actual job of sending the email message.</p> </div> <div class="paragraph"> <p>Let’s solve the problems one by one. First, let’s create the component. <code>EmailSender</code>, I’ll call it.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Component public class EmailSender { public boolean send(String to, String subject, String body) { // TODO: implement return false; } }</code></pre> </div> </div> <div class="paragraph"> <p>Then we can add it to the controller and update the endpoint logic as follows:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@RestController("email") public class EmailController { private final EmailSender emailSender; public EmailController(EmailSender emailSender) { this.emailSender = emailSender; } @PostMapping("/send") public String sendEmail(@RequestBody EmailRequestDto request) { boolean success = emailSender.send(request.to(), request.subject(), request.body()); return success ? "Email sent" : "Error sending email"; } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_integrating_with_the_first_email_provider">Integrating with the first email provider</h4> <div class="paragraph"> <p>Now, let’s make it work with one provider: let’s say Mailersend. To do that, we’ll follow their <a href="https://github.com/mailersend/mailersend-java?tab=readme-ov-file" target="_blank" rel="noopener">documentation</a>.</p> </div> <div class="paragraph"> <p>We add the new Maven dependency:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><dependency> <groupId>com.mailersend</groupId> <artifactId>java-sdk</artifactId> <version>1.0.0</version> </dependency></code></pre> </div> </div> <div class="paragraph"> <p>And we update the sender class as follows:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Component public class EmailSender { private static final Logger LOGGER = Logger.getLogger(EmailSender.class.getName()); @Value("${integration.mailersend.token}") private String token; public boolean send(String to, String subject, String body) { Email email = createEmail(to, subject, body); MailerSend sender = createSender(); return sendEmailUsingSender(sender, email); } private static Email createEmail(String to, String subject, String body) { Email email = new Email(); email.setFrom("Strategy Pattern In Spring Boot", "comlealceldeiro@strategy.com"); email.addRecipient(to, to); email.setSubject(subject); email.setPlain(body); return email; } private MailerSend createSender() { MailerSend ms = new MailerSend(); ms.setToken(token); return ms; } private static boolean sendEmailUsingSender(MailerSend sender, Email email) { LOGGER.info("Attempting to send email "); try { MailerSendResponse response = sender.emails().send(email); LOGGER.info("Sent email with id " + response.messageId); } catch (MailerSendException e) { LOGGER.warning("Email not sent"); return false; } return true; } }</code></pre> </div> </div> <div class="paragraph"> <p>Notice how we added the field <code>token</code> to be bound to the Spring Boot property <code>integration.mailersend.token</code>. This property can be set in the <code>application.properties</code> (or yml) file as follows:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties">integration.mailersend.token=eyJhbGciOiJIUzI1NiIsInR0Q8AOZ6RWm_rqbj9tYr8-J4</code></pre> </div> </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>In an actual production code, it’s safer to set the token through the cloud provider cli or secrets configuration. But it’s never safe to store it in plain text, except (maybe) for local development.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Hurray, our first email is on its way!</p> </div> </div> <div class="sect3"> <h4 id="_the_real_challenge">The real challenge</h4> <div class="paragraph"> <p>But we face a challenge here: one of the requirements says the application must be able to run in different organization and work with different email providers, but if this application is deployed in an environment where the email provider is different from Mailersend, it’ll fail.</p> </div> <div class="paragraph"> <p>The most "simple" solution anyone, with the most basic knowledge of Spring Boot, could think of, is to add a "flag property" in the <code>application.properties</code> corresponding to each environment. Then depending on the value of that variable at runtime—which will be different in each environment—, we would use a different logic inside our <code>EmailSender#send</code> to connect to a different email API provider. That’s it, through some <code>if</code>/<code>swtich</code> checks or similar. Some other alternatives along these lines would work too.</p> </div> <div class="paragraph"> <p>That’s not an incorrect solution. However, in the long term, it’ll become harder to maintain as the class grows bigger over time and new provider integrations are added. It’ll get to the point that it’ll hinder the development itself.</p> </div> <div class="paragraph"> <p>A better solution would be creating a different <code>EmailSender</code> component for each integration we want to support, and "load the correct one" at runtime time instead of having a fixed instance in <code>EmailController</code>.</p> </div> </div> <div class="sect3"> <h4 id="_spring_profiles_to_the_rescue">Spring profiles to the rescue</h4> <div class="paragraph"> <p>Spring <a href="https://docs.spring.io/spring-boot/reference/features/profiles.html" target="_blank" rel="noopener">profiles</a> provide a way for us to segregate parts of an application configuration and make it be available only in certain environment(s).</p> </div> <div class="paragraph"> <p>This feature, together with configuration components and spring beans, is a powerful tool at our disposal here.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>A <a href="https://docs.spring.io/spring-framework/reference/core/beans/definition.html" target="_blank" rel="noopener">spring bean</a> is any component we define whose life-cycle is managed by the spring <a href="https://docs.spring.io/spring-framework/reference/core/beans.html#page-title" target="_blank" rel="noopener">container</a>. One of the most common ways to declare a bean is by using the <a href="https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/Bean.html" target="_blank" rel="noopener"><code>@Bean</code> annotation</a>.</p> </div> <div class="paragraph"> <p>Scoping a component to a specific profile is usually done by using the <code>@Profiles</code> annotation on the component.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>So, we’re going to use this feature to have one bean per strategy. Each strategy will correspond to the logic to send the email through each email provider. Then, when the application is deployed in a given environment, the bean (Java class component) with the strategy that corresponds to the integration for that environment will be <a href="https://docs.spring.io/spring-framework/reference/core/beans/annotation-config/autowired.html" target="_blank" rel="noopener">wired</a>, that is it <a href="https://docs.spring.io/spring-framework/reference/core/beans/dependencies/factory-collaborators.html" target="_blank" rel="noopener">injected</a>, into the component that requires it.</p> </div> <div class="sect4"> <h5 id="_support_to_all_providers">Support to all providers</h5> <div class="paragraph"> <p>Let’s code it.</p> </div> <div class="paragraph"> <p>First, we need to find a way to keep a single dependency in our controller. We don’t want to declare one dependency per strategy. To achieve this, we’ll use an interface: <code>EmailSender</code> (we’ll rename the class with that name, don’t worry).</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public interface EmailSender { boolean send(String to, String subject, String body); }</code></pre> </div> </div> <div class="paragraph"> <p>Next, let’s update our previous <code>EmailSender</code> class. We’ll rename it to <code>MailerSendEmailSender</code> and make it implement <code>EmailSender</code> and override the <code>send</code> method. The rest of the code stays the same.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Component public class MailerSendEmailSender implements EmailSender { // ... rest of the code unchanged @Override public boolean send(String to, String subject, String body) { // ... rest of the code unchanged } }</code></pre> </div> </div> <div class="paragraph"> <p>By doing this, Spring Boot we’ll manage the dependency injection for us automatically. That is, at runtime it will locate a bean that implements <code>EmailSender</code> and inject it in the <code>EmailController</code> class.</p> </div> <div class="paragraph"> <p>So far this has been a code refactor, we’re still not giving support to other providers.</p> </div> <div class="paragraph"> <p>Let’s implement the rest of them—I’ll leave the details out, but the gist should be clear from this example.</p> </div> <div class="paragraph"> <p>Twilio.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Component public class TwilioEmailSender implements EmailSender { @Override public boolean send(String to, String subject, String body) { // ... logic to send emails through the Twilio API } }</code></pre> </div> </div> <div class="paragraph"> <p>Mailgun.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Component public class MailgunEmailSender implements EmailSender { @Override public boolean send(String to, String subject, String body) { // ... logic to send emails through the Mailgun API } }</code></pre> </div> </div> <div class="paragraph"> <p>Mailjet.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Component public class MailjetEmailSender implements EmailSender { @Override public boolean send(String to, String subject, String body) { // ... logic to send emails through the Mailjet API } }</code></pre> </div> </div> <div class="paragraph"> <p>At this point, if we try to run the application, we’ll get an error like this one:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-console hljs" data-lang="console">Parameter 0 of constructor in com.lealceldeiro.strategysb.EmailController required a single bean, but 4 were found: - mailerSendEmailSender: defined in file [~/MailerSendEmailSender.class] - mailgunEmailSender: defined in file [~/MailgunEmailSender.class] - mailjetEmailSender: defined in file [~/MailjetEmailSender.class] - twilioEmailSender: defined in file [~/TwilioEmailSender.class] This may be due to missing parameter name information Action: Consider marking one of the beans as @Primary, updating the consumer to accept multiple beans, or using @Qualifier to identify the bean that should be consumed</code></pre> </div> </div> <div class="paragraph"> <p>The framework message is pretty clear: we’re asking for one bean in <code>EmailController</code> but Spring found four of them and there’s no information that tells it which one to pick over the others.</p> </div> <div class="paragraph"> <p>The options to fix this are also available in the message itself:</p> </div> <div class="ulist"> <ul> <li> <p>Define one of the beans as <em>primary</em>: annotate one of the implementations as <code>@Primary</code></p> </li> <li> <p>Accept multiple beans in the controller instead of one: in the controller, receive in the constructor the argument as <code>List<EmailSender> senders</code> instead of <code>EmailSender emailSender</code></p> </li> <li> <p>Use <code>@Qualifier</code> in the controller constructor argument: i.e.: <code>@Qualifier("mailerSendEmailSender") EmailSender emailSender</code></p> </li> </ul> </div> <div class="paragraph"> <p>When we face situations like this one, we must always evaluate what our use case is and what option makes the most sense. For example, for this particular case using <code>@Primary</code> for one of the providers would be enough.</p> </div> <div class="paragraph"> <p>However, remember that our primary goal here was to have one bean/component or the other based on the environment the application is running on. This gives us another option to "fix" the previous error and, at the same time, give a solution to our initial requirement. We’ll declare for each component for which profile they’ll be available.</p> </div> <div class="paragraph"> <p>To do this, we’ll use the mentioned <a href="https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/Profile.html" target="_blank" rel="noopener"><code>@Profile</code></a> annotation.</p> </div> <div class="paragraph"> <p>Mailersend.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Profile("mailersend") @Component public class MailerSendEmailSender implements EmailSender { // ... }</code></pre> </div> </div> <div class="paragraph"> <p>Twilio.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Profile("twilio") @Component public class TwilioEmailSender implements EmailSender { // ... }</code></pre> </div> </div> <div class="paragraph"> <p>Mailgun.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Profile("mailgun") @Component public class MailgunEmailSender implements EmailSender { // ... }</code></pre> </div> </div> <div class="paragraph"> <p>Mailjet.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Profile("mailjet") @Component public class MailjetEmailSender implements EmailSender { // ... }</code></pre> </div> </div> <div class="paragraph"> <p>Have in mind that now, we must specify a profile for our application to start, otherwise Spring won’t find the correct bean associated with the profile and will fail.</p> </div> <div class="paragraph"> <p>From IntelliJ IDEA, you can do it from the <a href="https://www.jetbrains.com/help/idea/run-debug-configuration-spring-boot.html" target="_blank" rel="noopener">Spring Boot Run Configuration</a>, like this:</p> </div> <div class="imageblock"> <div class="content"> <img src="images/07/run-debug-configuration-spring-boot.webp" alt="Spring Boot Run Configuration in IntelliJ IDEA" width="650" height="650"> </div> </div> <div class="paragraph"> <p>That’s it for this use case. From now on, when we start this application by using one of the four available profiles, Spring Boot will locate for us the component that’s defined for that given profile and inject it into the <code>EmailController</code>.</p> </div> <div class="paragraph"> <p>For experienced Spring Boot developers, this might look like a trivial example. But when we implement something like this out of many years of practice, how many times do we stop and think for a second we’re using the "Strategy" pattern? Sometimes it’s useful to do it ;)</p> </div> </div> </div> </div> <div class="sect2"> <h3 id="_other_applications">Other applications</h3> <div class="paragraph"> <p>What’s shown in the previous example is just that: ONE example. The number of use cases where we can apply it is humongous: in integration with third party services, sorting algorithms, notification services, file compression, authentication mechanisms, and much more.</p> </div> </div> <div class="sect2"> <h3 id="_strategy_in_spring_boot_itself">Strategy in Spring Boot itself</h3> <div class="paragraph"> <p>Aside from using this pattern in our applications to fulfil specific use cases, it’s also widely used in many frameworks, including Spring Boot.</p> </div> <div class="paragraph"> <p>For example, <a href="https://spring.io/projects/spring-data" target="_blank" rel="noopener">Spring Data</a> provides a flexible way to interact with databases. Depending on the application’s requirements, different data access strategies can be used, such as JDBC, JPA, or any other of the many available.</p> </div> <div class="paragraph"> <p>The same remains true for other techniques related to transaction management, view resolution in Spring MVC, Spring Security, caching abstractions, message converters, and more.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_github_repository">GitHub repository</h2> <div class="sectionbody"> <div class="paragraph"> <p>The example code posted in this article can be found in this <a href="https://github.com/lealceldeiro/com-lealceldeiro-strategy-sb">public GitHub repository</a>.</p> </div> </div> </div> asiel@lealceldeiro.com(Asiel Leal Celdeiro) https://lealceldeiro.com/articles/2024/access-control-in-java.html Wed, 17 Apr 2024 00:00:00 +0000 articles/2024/access-control-in-java.html <div id="toc" class="toc"> <div id="toctitle">In this article</div> <ul class="sectlevel1"> <li><a href="#_whats_access_control_in_java">What’s "access control" in Java?</a></li> <li><a href="#_hows_accessibility_to_an_entity_determined">How’s accessibility to an entity determined?</a> <ul class="sectlevel2"> <li><a href="#_top_level_classes">Top level classes</a></li> <li><a href="#_members_and_constructors">Members and constructors</a></li> <li><a href="#_array_types">Array types</a></li> </ul> </li> <li><a href="#_wrap_up">Wrap up</a> <ul class="sectlevel2"> <li><a href="#_compilation_units_located_in_different_modules">Compilation units located in different modules</a></li> <li><a href="#compilation_units_within_the_same_module_or_exported_to_another_modules">Compilation units within the same module or exported to another module(s)</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>The access control mechanisms in Java allow us to have a more secure way of building our applications, libraries, and code in general. In this article, you’ll learn what are the access controls implemented by the Java platform, how to use them and have a better picture of how they work in general.</p> </div> </div> </div> <div class="sect1"> <h2 id="_whats_access_control_in_java">What’s "access control" in Java?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Access control refers to the mechanisms defined by Java to guarantee that packages, classes, etc. are accessible only to those entities which have the correct permissions and not to others which are not entitled to access them.</p> </div> <div class="paragraph"> <p>This sometimes can be seen as a restrictive behavior, but it’s more than that: it shields users of a class or package from depending on specific implementation details that are irrelevant to them and that could potentially break their code if such details are changed.</p> </div> <div class="paragraph"> <p>In short, if access to an entity is permitted, that entity is said to be <em>accessible</em>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_hows_accessibility_to_an_entity_determined">How’s accessibility to an entity determined?</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_top_level_classes">Top level classes</h3> <div class="paragraph"> <p>Top level class can be declared only either <code>public</code> or <em>package private</em>, any other attempt to specify an access modifier would result in a compilation error.</p> </div> <div class="sect3"> <h4 id="_public_classes">Public classes</h4> <div class="paragraph"> <p>Let’s start with the most permissive one. If a top level class or interface is declared <code>public</code>, then it may be accessed by any code declared within the same module.</p> </div> <div class="paragraph"> <p>On top of that, if such a class or interface is a member of a package that is exported by its module, then it’ll also be accessible by code located in another module to which the package is exported, as long as the <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-7.html#jls-7.3" target="_blank" rel="noopener">compilation unit</a> in which the class or interfaces is declared is visible to that other module (<a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-6.html#jls-6.6.1" target="_blank" rel="noopener">§6.6.1</a>).</p> </div> <div class="paragraph"> <p>In contrast, if the class or interface is part of a module that’s not exported, it’ll be accessible only by code located in the same module.</p> </div> </div> <div class="sect3"> <h4 id="_package_access">package access</h4> <div class="paragraph"> <p>When a top level class or interface is declared as "package private" it’ll be accessible only from code located within the same package.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <em>package access</em> is the implicit (default) access given when no modifier (<code>public</code> or <code>private</code>) is specified. </td> </tr> </table> </div> </div> </div> <div class="sect2"> <h3 id="_members_and_constructors">Members and constructors</h3> <div class="paragraph"> <p>A member (class, interface, field, or method) of a class, interface, type parameter, or reference type, or a constructor of a class, is accessible only if (<a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-6.html#jls-6.6.1" target="_blank" rel="noopener">§6.6.1</a>):</p> </div> <div class="ulist"> <ul> <li> <p>the class, interface, type parameter, or reference type is accessible, and</p> </li> <li> <p>the member or constructor is declared to permit access:</p> <div class="olist arabic"> <ol class="arabic"> <li> <p>If the member of constructor is declared <code>public</code>, then access is permitted</p> </li> <li> <p>Otherwise, if the member or constructor is declared <code>protected</code>, then access is permitted only when:</p> <div class="ulist"> <ul> <li> <p>the access occurs from within the package containing the class in which the protected member or constructor is declared</p> </li> <li> <p>or, the code that tries to access the protected member or constructor of an object is responsible for the implementation of that object (<a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-6.html#jls-6.6.2" target="_blank" rel="noopener">§6.6.2</a>).</p> </li> </ul> </div> </li> <li> <p>Otherwise, if the member or constructor is declared with package access, then access is permitted only when the access occurs from within the package in which the class, interface, type parameter, or reference type is declared.</p> </li> <li> <p>Otherwise, when the member or constructor is declared <code>private</code>, then access is permitted only when:</p> <div class="ulist"> <ul> <li> <p>the access occurs from within the body of the top level class or interface that encloses the declaration of the member or constructor</p> </li> <li> <p>or, the access occurs in the <code>permits</code> clause of the top level class or interface that enclose the declaration of the member</p> </li> <li> <p>or, the access occurs in the <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.10.1" target="_blank" rel="noopener">record component list</a> of the top level record class that encloses the declaration of the member</p> </li> </ul> </div> </li> </ol> </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"> All members of interfaces lacking access modifiers are implicitly <code>public</code>. </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_array_types">Array types</h3> <div class="paragraph"> <p>An array type is accessible if, and only if, its element type is accessible.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_wrap_up">Wrap up</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_compilation_units_located_in_different_modules">Compilation units located in different modules</h3> <div class="paragraph"> <p>When two compilation units (source files), let’s say class <code>A</code> and <code>B</code> are located in different modules, let’s say <code>moduleA</code> and <code>moduleB</code> respectively, if class <code>A</code> is exported by <code>moduleA</code> to <code>moduleB</code>, then class <code>A</code> and its members and constructor(s) might be accessible to class <code>B</code>, following the previously explained rules and summarized in the <a href="#compilation_units_within_the_same_module_or_exported_to_another_modules">next section</a>.</p> </div> <div class="paragraph"> <p>Otherwise, if class <code>A</code> is not exported from <code>moduleA</code> to <code>moduleB</code>, it won’t be accessible by class <code>B</code>, regardless of the access modifier specified (and the next section doesn’t apply), period.</p> </div> </div> <div class="sect2"> <h3 id="compilation_units_within_the_same_module_or_exported_to_another_modules">Compilation units within the same module or exported to another module(s)</h3> <div class="paragraph"> <p>Given we have some compilation units (source files) accessible to one another, from a module visibility point of view, then we can summarize their accessibility as follows.</p> </div> <div class="paragraph"> <p>In the next two tables, you can see, respectively, the different access levels for top level classes, and for members and constructor. If you’re just starting to learn or practice this content, it may be useful to keep them at hand—kind of cheat sheet. However, make sure you understand all the details and nuances previously explained and, ideally, the content from the linked resources.</p> </div> <table class="tableblock frame-all grid-all fit-content"> <caption class="title">Table 1. Access levels for top level classes, interfaces, etc. <code>√</code> means accessible, blank means not accessible</caption> <colgroup> <col> <col> <col> <col> <col> <col> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top"></th> <th class="tableblock halign-left valign-top">Type (class, interface, etc.)</th> <th class="tableblock halign-left valign-top">Unrelated type within the package containing the accessed type</th> <th class="tableblock halign-left valign-top">Subtype in the same package</th> <th class="tableblock halign-left valign-top">Subtype in a different package</th> <th class="tableblock halign-left valign-top">Any other code that tries to access it</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>public</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><em>package private</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> </tr> </tbody> </table> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> Remember, we can’t declare a top level class, interface, etc. as <code>private</code> or <code>protected</code>, otherwise the code won’t compile. </td> </tr> </table> </div> <table class="tableblock frame-all grid-all fit-content"> <caption class="title">Table 2. Access levels for members and constructors. <code>√</code> means accessible, blank means not accessible</caption> <colgroup> <col> <col> <col> <col> <col> <col> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top"></th> <th class="tableblock halign-left valign-top">Enclosing type (class/interface, etc.)</th> <th class="tableblock halign-left valign-top">Unrelated type within the package containing the enclosing type</th> <th class="tableblock halign-left valign-top">Subtype in the same package</th> <th class="tableblock halign-left valign-top">Subtype in a different package</th> <th class="tableblock halign-left valign-top">Any other code that tries to access it</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>public</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>protected</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><em>package private</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>private</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>√</code></p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> </tr> </tbody> </table> </div> </div> </div> asiel@lealceldeiro.com(Asiel Leal Celdeiro) https://lealceldeiro.com/articles/2024/kanban.html Fri, 12 Apr 2024 00:00:00 +0000 articles/2024/kanban.html <div id="toc" class="toc"> <div id="toctitle">In this article</div> <ul class="sectlevel1"> <li><a href="#_getting_started">Getting started</a></li> <li><a href="#_what_is_kanban">What is Kanban?</a></li> <li><a href="#_using_kanban">Using Kanban</a> <ul class="sectlevel2"> <li><a href="#_can_we_apply_it">Can we apply it?</a></li> <li><a href="#_how_could_it_help_us">How could it help us?</a></li> <li><a href="#_what_changes_are_required_to_use_kanban">What changes are required to use Kanban?</a></li> </ul> </li> <li><a href="#_how_to_get_started_with_it">How to get started with it?</a> <ul class="sectlevel2"> <li><a href="#_map_the_workflow">Map the workflow</a></li> <li><a href="#_visualize_the_work_in_progress">Visualize the work in progress</a></li> <li><a href="#_set_initial_wip_limits">Set initial WIP limits</a></li> <li><a href="#_kanban_is_a_pull_system">Kanban is a "pull" system</a></li> <li><a href="#_bottlenecks">Bottlenecks</a></li> <li><a href="#_monitor_the_workflow_and_adapt">Monitor the workflow and adapt</a></li> </ul> </li> <li><a href="#_other_considerations">Other considerations</a> <ul class="sectlevel2"> <li><a href="#_classes_of_services">Classes of services</a></li> <li><a href="#_can_we_use_practices_from_other_agile_methodologies_like_scrum">Can we use practices from other agile methodologies, like Scrum?</a></li> </ul> </li> <li><a href="#_final_thoughts">Final thoughts</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Kanban is a tool that aims to improve efficiency by reducing waste of time and doing things more efficiently. In this article, we’ll see a quick introduction to this tool, what it is, how to use it, and whether it can be applied (and how) to our work process. The views and knowledge expressed here are those from the perspective of a Software Engineer focused on backend development—not an expert in agile methodologies.</p> </div> </div> </div> <div class="sect1"> <h2 id="_getting_started">Getting started</h2> <div class="sectionbody"> <div class="paragraph"> <p>No matter what business we’re in, we’re always finding ways to make things more efficiently. Lean methodologies were introduced with that purpose, and they were born in manufacturing environments but can be applied to almost any kind of business activity or process.</p> </div> <div class="paragraph"> <p>They can be seen as a set of tools that can be adapted or modified to any environment, according to the problem being solved.</p> </div> <div class="paragraph"> <p>One of these tools is <strong>Kanban</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_what_is_kanban">What is Kanban?</h2> <div class="sectionbody"> <div class="paragraph"> <p>In every business, there’s always a desired result that’s preceded by a series of steps or tasks. These steps or tasks almost always carry some form of result, let it be a document, a piece of information, or any other output that is also used as the input for another step or task.</p> </div> <div class="paragraph"> <p>Not having these results (and on time) can cause delays for the final customer and, consequently, lost in our business. On the flip side, having too many results (documents, deliverables, etc.) can become cumbersome to manage and can also have the same undesired effects.</p> </div> <div class="paragraph"> <p>This is where Kanban comes in: it helps us in learning and managing an optimal flow of work within the process.</p> </div> <div class="paragraph"> <p>Some basic rules to implement Kanban are:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Visualize the workflow: A visual representation of the workflow lets us see how tasks move from being "not done" to "done right".</p> </li> <li> <p>Limit work in process/progress (WIP): <a href="https://www.youtube.com/watch?v=hGJpez7rvc0" target="_blank" rel="noopener">Get more done by doing less</a> (at the same time). There’s a limit in the tasks we can do at the same time, going beyond that limit will only decrease our productivity. This is the same principle we apply in programming: <a href="https://en.wikipedia.org/wiki/Divide-and-conquer_algorithm" target="_blank" rel="noopener">divide and conquer</a>: we should decompose "bigger" tasks into smaller ones, and do them one at the time to get them done correctly. Kanban metrics allow us to find that "optimal" number of tasks.</p> </li> <li> <p>Measure and improve the flow: Improvements should always be a result of decisions made in an informed way. Kanban is no different. In order for us to improve those areas where we’re not being as productive as possible, we need to first measure the steps, tasks. How much is this task taking and why? How much did we take to release feature XYZ? How many hours did we spend in the analysis of feature ABC? Finding a good tool that allows us to measure our tasks/steps properly is very important to enhance our processes. Some examples are <a href="https://kanbantool.com/" target="_blank" rel="noopener">Kanbantool</a> and <a href="https://www.atlassian.com/software/jira/features/kanban-boards" target="_blank" rel="noopener">Jira</a>.</p> </li> </ol> </div> <div class="paragraph"> <p>One good thing about Kanban is that we don’t have to change what we may already be doing in our business. We simply adapt the Kanban tool to our processes, to start measuring, adjusting and optimizing our tasks for maximum efficiency.</p> </div> <div class="paragraph"> <p>Put in another way: we use Kanban in our existing business to identify ways to improve our already existing processes; we don’t need to change our processes at once and "implement Kanban"—we don’t lose the good things we’re doing already.</p> </div> </div> </div> <div class="sect1"> <h2 id="_using_kanban">Using Kanban</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_can_we_apply_it">Can we apply it?</h3> <div class="paragraph"> <p>Whenever we consider using some new tool, framework, process, etc. we immediately think: can we apply this?, will it work for me?</p> </div> <div class="paragraph"> <p>It’s no different with Kanban. Can we apply it in the software development processes?</p> </div> <div class="paragraph"> <p>Yes. Many would agree with me. Many others would say "yes, but some Scrum-like methodology would fit better for my use case"—and that may be completely right as well. As always, the answer is "it depends".</p> </div> <div class="paragraph"> <p>Software development teams use Kanban to organize their work. That is, (roughly speaking,) defining a backlog of tasks, prioritizing them, doing some analysis work, "moving" them to "development", "review", "done", and the list goes on and on, as long as the teams see it fit.</p> </div> <div class="paragraph"> <p>That’s the interesting thing about it: it’s not a restrictive framework that dictates "what must be done", instead it offers guides on how things could improve, rather than specific actions, so it can be easily adopted by different businesses.</p> </div> </div> <div class="sect2"> <h3 id="_how_could_it_help_us">How could it help us?</h3> <div class="paragraph"> <p>Kanban should not be "enforced". As with any other tool, we must be able to identify pain points we have in our teams (or solo-team) and check if the tool can really help us.</p> </div> <div class="paragraph"> <p>For example, if we feel we’re always busy, and yet we can’t get anything done/completed. Or, if we feel the process, as a whole, is not as efficient as it could be. Or maybe we simply don’t have an answer to common questions like "where are we at now?", "when will task XYZ be completed?", "who’s working on feature ABC?", or "what should I work on now?".</p> </div> <div class="paragraph"> <p>In such cases, it may be worth taking some time and consider something like Kanban; something that could lead to improve our efficiency and remove waste of time and resources.</p> </div> </div> <div class="sect2"> <h3 id="_what_changes_are_required_to_use_kanban">What changes are required to use Kanban?</h3> <div class="paragraph"> <p>Good news! There’s no need to overhaul the whole business practices in order for us to adopt Kanban. It provides the means to visualize what we’re already doing and which parts could be tweaked to be more efficient. On top of that, the changes required to make things better can be implemented gradually—no need to throw everything away and start from scratch!</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_how_to_get_started_with_it">How to get started with it?</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_map_the_workflow">Map the workflow</h3> <div class="paragraph"> <p>That’s the most challenging part of almost anything: getting started. Once we get that little first step, things start to turn smoother.</p> </div> <div class="paragraph"> <p>So it’s important to know how to take that first step.</p> </div> <div class="paragraph"> <p>One approach is to make something like a map or visual representation of our current workflow. This means identifying major processes in our organization/business, department, area, etc. It’s here where we also identify (mentioned in no particular order):</p> </div> <div class="ulist"> <ul> <li> <p>which are the steps/tasks we currently have in our process?</p> </li> <li> <p>where are they coming from?</p> </li> <li> <p>how are they defined, assigned and prioritized?</p> </li> </ul> </div> <div class="paragraph"> <p>With answers to questions like this, we create one column for the Kanban board. So, for a software development team, we could have the following columns:</p> </div> <div class="ulist"> <ul> <li> <p>Backlog</p> </li> <li> <p>Analysis</p> </li> <li> <p>Design</p> </li> <li> <p>Review</p> </li> <li> <p>Development</p> </li> <li> <p>Code Review</p> </li> <li> <p>Testing</p> </li> <li> <p>Release</p> </li> <li> <p>Support</p> </li> </ul> </div> <div class="paragraph"> <p>It’s after we do this step that we can identify improvements in our current workflow, so it’s normal if some of the things we’re doing are not as efficient as we’d like them to be. That’s expected: it’s from this point from where we start to see areas of improvements and form where we can start to enhance our flow; so it’s important to not try to "beatify" the current state of our processes: we need to see our flaws, so we can tackle them.</p> </div> <div class="paragraph"> <p>Also, at this point, it’s a good idea to define how many work in progress (WIP) we’re willing to keep. For example, a developer shouldn’t have more than one feature ticket in state "Development" at the same time; but probably a marketing specialist can handle three or more tickets with the goal to define different marketing strategies associated with different partners. These limits can then be changed gradually as the team monitors their speed and results in each of the steps.</p> </div> <div class="paragraph"> <p>Once we have our workflow steps defined, it’s time to draw those as columns in a board. It can be done in almost anything we want: a physical whiteboard, a table, a piece of paper, a corkboard, a Kanban board on Jira.</p> </div> </div> <div class="sect2"> <h3 id="_visualize_the_work_in_progress">Visualize the work in progress</h3> <div class="paragraph"> <p>It’s time to visualize the work in progress the team is doing. It’s now when we start adding the tasks to the board and track how they move from one column (step) to another. Also, it’s a good idea to display for each task some meta-data such as creation date, deadline, priority, type, priority, description, notes, definition of "done", history and any other piece of data that helps in monitoring each task. It’s good to display on the board as well who’s working on each task, unless it’s a solo-team.</p> </div> <div class="paragraph"> <p>Nowadays, tools like Jira, make this part trivial, as its boards already bring all these fields really easy to be edited.</p> </div> </div> <div class="sect2"> <h3 id="_set_initial_wip_limits">Set initial WIP limits</h3> <div class="paragraph"> <p>As mentioned before, it’s important to define some initials WIP limits. Sometimes this is challenging to do: how do we know the ideal amount of work in progress we can handle? But we must start somewhere, right?</p> </div> <div class="paragraph"> <p>Two approaches can be applied here:</p> </div> <div class="ulist"> <ul> <li> <p>Start with low limits and increase them later as the workflow is monitored: this one can be painful because we may feel tempted to take more work than the one permitted by the limits, but it usually gives better results.</p> </li> <li> <p>Start intentionally with high limits and lower them later as the workflow is monitored: this one may have slower results, but it could easy the adoption within the team.</p> </li> </ul> </div> <div class="paragraph"> <p>During this time, it’s good to involve the whole team in documenting the process and setting realistic WIP limits everyone is willing to enforce.</p> </div> <div class="sect3"> <h4 id="_why_is_it_so_important_to_respect_the_wip_limits">Why is it so important to respect the WIP limits?</h4> <div class="paragraph"> <p>By working on as many tasks as we can really handle has two major benefits:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>It reduces the time we take to get anything done (<em>lead time</em>)</p> </li> <li> <p>It improves quality by giving greater focus to fewer tasks</p> </li> </ol> </div> <div class="paragraph"> <p>Once these limits have been defined, it’s good to somehow show them on the board for each of the columns. This helps in having a visual representation of how many tasks a given team member can be working on simultaneously. It’s also important to always keep an eye on everyone’s' current capacity and beware of anyone wanting to go beyond the limits. In such cases, the team could call a meeting to understand what’s the rationale behind it and discuss it further if needed.</p> </div> </div> </div> <div class="sect2"> <h3 id="_kanban_is_a_pull_system">Kanban is a "pull" system</h3> <div class="paragraph"> <p>The idea of Kanban is that each phase/column "pulls" the work from the previous stage/column, signaling the previous stage "to make another one" (terms from the manufacturing days). This is intentional: the idea is that each stage pulls new work only when it’s possible to complete it. This way, the WIP limits are enforced for each stage.</p> </div> <div class="paragraph"> <p>This mechanism is opposed to a "push system" where each stage would complete the work on it and would "push" it to the next stage, regardless of the workload there and without having in mind the WIP limits.</p> </div> <div class="paragraph"> <p>Put in another way: each team member takes (pull) new tasks only when they’re ready to do the work, and it becomes his/her responsibility until the task is completed for that stage. This doesn’t mean one person can’t complete the tasks associated to the same concept in different stages, quite the opposite. Sometimes it’s the same person who "moves" a task from one state (column/stage) to another, until it’s "done". Again, Kanban is very flexible, and it’s here to help us with our flow, not to put restrictions.</p> </div> </div> <div class="sect2"> <h3 id="_bottlenecks">Bottlenecks</h3> <div class="paragraph"> <p>Once we have a visual representation of our process(es), ideally in a Kanban board, we can see at a glance where in the workflow each task is, and it’s really easy to spot bottlenecks early. When the WIP limits are set appropriately, we usually hit a limit as soon as a bottleneck starts to form. That’s why, in part, the power of Kanban comes from the fact that everyone can see when a problem (like bottleneck) is forming and take action early in the workflow, before more work is piled up and everyone needs to start jumping from task to task: this is when clarity is lost because of so many context switches.</p> </div> </div> <div class="sect2"> <h3 id="_monitor_the_workflow_and_adapt">Monitor the workflow and adapt</h3> <div class="paragraph"> <p>Kanban doesn’t force us to monitor, adapt or learn from mistakes; but it’s generally a good idea to do so. Otherwise, we’re not benefitting completely from having a well-defined process structure and WIP limits.</p> </div> <div class="paragraph"> <p>Two tools that are really useful for tracking improvements are <em>lead time</em> and <em>cycle time</em>. Lead time is basically the total time it takes to get something done from the moment someone asks for it until it’s completed. Cycle time is the amount of time spent on a work item by a person or a team up until it’s ready to be delivered.</p> </div> <div class="paragraph"> <p>It’s also generally a good idea for the team to review the metrics and reflect on what’s being done right and what could be improved. This is how, iteration after iteration, the team can reach a point of "optimal" flow in the process. The space and format of this is different for each team. Some things that I’ve seen work in the pass is to have regular meetings, let it be weekly, bi-weekly, or with any other schedule, where everyone is free to express their ideas and observation of how the workflow has changed since the last iteration.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_other_considerations">Other considerations</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_classes_of_services">Classes of services</h3> <div class="paragraph"> <p>Different tasks have different intrinsic value to customers, different risks, different priorities, etc. By defining "classes of services", policies, and "rules" associated with them, we can change the value that’s delivered and improve the overall workflow.</p> </div> <div class="paragraph"> <p>For example, in a software development team, there could be a class of service called "production bug", which would describe a ticket whose result impacts the customers and the organization directly. Because of this, resolving it is a top priority The following "rules" would apply:</p> </div> <div class="ulist"> <ul> <li> <p>it’s a top-priority task</p> </li> <li> <p>it can break WIP limits</p> </li> <li> <p>it can skip the steps: Design, Review, and Support</p> </li> <li> <p>it can be released without a product owner approval</p> </li> <li> <p>it has associated a label "deliver ASAP"</p> </li> </ul> </div> <div class="paragraph"> <p>Class of service is a powerful tool that can be implemented and adapted in a variety of ways to optimize the value delivered by the team.</p> </div> </div> <div class="sect2"> <h3 id="_can_we_use_practices_from_other_agile_methodologies_like_scrum">Can we use practices from other agile methodologies, like Scrum?</h3> <div class="paragraph"> <p>Yes, we can. Kanban doesn’t define what steps, rituals, meetings, or similar team practices are used in the team’s workflow. It is a tool to be used to improve our workflow, in general, but there’s no hard rule that stops us from experimenting and implementing other tools or framework that could also help us.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_final_thoughts">Final thoughts</h2> <div class="sectionbody"> <div class="paragraph"> <p>After the processes are defined and Kanban is implemented, we must make sure the procedures are explicit. This way, we make sure everyone understands it as much as possible; and, in case there are doubts, they must be addressed as soon as possible to make sure the whole team is aligned.</p> </div> <div class="paragraph"> <p>This means, the established policies must be clear, specific, readily available and reviewed/revised regularly.</p> </div> <div class="paragraph"> <p>We must always keep in mind what’s the goal of implementing Kanban: to keep improving our processes through reflection, refinement, experimentation, and creating and managing metrics. Tools like Jira can help a lot in this sense.</p> </div> </div> </div> asiel@lealceldeiro.com(Asiel Leal Celdeiro) https://lealceldeiro.com/articles/2024/the-static-keyword-in-java.html Thu, 22 Feb 2024 00:00:00 +0000 articles/2024/the-static-keyword-in-java.html <div id="toc" class="toc"> <div id="toctitle">In this article</div> <ul class="sectlevel1"> <li><a href="#_whats_the_static_keyword_in_java">What’s the <code>static</code> keyword in Java?</a></li> <li><a href="#_use_cases_for_the_static_keyword">Use cases for the <code>static</code> keyword</a> <ul class="sectlevel2"> <li><a href="#_static_classes_and_interfaces">Static classes and interfaces</a></li> <li><a href="#_static_fields">Static fields</a></li> <li><a href="#_static_methods">Static methods</a></li> <li><a href="#_static_initializers">Static initializers</a></li> <li><a href="#_static_imports">Static imports</a></li> </ul> </li> <li><a href="#_additional_considerations">Additional considerations</a></li> <li><a href="#_final_thoughts">Final thoughts</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>In the world of Java programming, the <code>static</code> keyword plays a significant role, often thought of as a fundamental concept to grasp. However, its nuances can sometimes be elusive, especially for those new to the language. In this article we’ll go over this construct and some of the details to have in mind when using it in our code.</p> </div> </div> </div> <div class="sect1"> <h2 id="_whats_the_static_keyword_in_java">What’s the <code>static</code> keyword in Java?</h2> <div class="sectionbody"> <div class="quoteblock"> <blockquote> <div class="paragraph"> <p><strong>static</strong></p> </div> <div class="paragraph"> <p>[Computing] (of a process or variable) not able to be changed during a set period, for example, while a program is running.</p> </div> </blockquote> <div class="attribution"> — Oxford English Dictionary </div> </div> <div class="paragraph"> <p>That’s how the Oxford English Dictionary defines <em>static</em> as a word in the field of computing. <em>Not able to change;</em> that’s the most important part.</p> </div> <div class="paragraph"> <p>Ok, we didn’t have to check the dictionary to know that: when something is static, it doesn’t change. For example, a <a href="https://en.wikipedia.org/wiki/Lighthouse" target="_blank" rel="noopener">lighthouse</a> is static in the sense that it doesn’t move from one place to another, like animals do. Although the lantern(s) and related components move, the tower structure <em>doesn’t change its position</em> on the soil.</p> </div> <div class="paragraph"> <p>How much does this meaning relate to the <code>static</code> keyword in Java?</p> </div> <div class="paragraph"> <p>Very much!</p> </div> <div class="paragraph"> <p>The <code>static</code> keyword in Java can be used to modify the definition of <a href="/articles/2024/java-oop-classes-and-objects.html#what-are-java-classes" target="_blank" rel="noopener">classes</a>, <a href="/articles/2024/java-oop-classes-and-objects.html#fields" target="_blank" rel="noopener">fields</a>, <a href="/articles/2024/java-oop-classes-and-objects.html#methods" target="_blank" rel="noopener">methods</a>, initializers, and more. It’s always used to reflect a sense of <em>not changing its [the component’s] behavior</em> depending on other factors, such as an object state.</p> </div> <div class="paragraph"> <p>Let’s see some use cases along with some meaningful examples.</p> </div> </div> </div> <div class="sect1"> <h2 id="_use_cases_for_the_static_keyword">Use cases for the <code>static</code> keyword</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_static_classes_and_interfaces">Static classes and interfaces</h3> <div class="paragraph"> <p>As we <a href="/articles/2024/java-oop-classes-and-objects.html#nested-classes" target="_blank" rel="noopener">saw previously</a>, we can declare inner classes and interfaces, that’s it, classes and interfaces as members of other classes and interfaces. For example:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">class A { class B { } }</code></pre> </div> </div> <div class="paragraph"> <p>In the previous code, <code>B</code> is an inner class. It’s a member of <code>A</code> (see <a href="https://docs.oracle.com/javase/tutorial/java/javaOO/nested.html" target="_blank" rel="noopener">tutorial</a> for a full example). This is a code smell, because to create an instance of <code>B</code>, we must create first an instance of <code>A</code>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">var a = new A(); var b = a.new B();</code></pre> </div> </div> <div class="paragraph"> <p>or the shorter version:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">var b = new A().new B();</code></pre> </div> </div> <div class="paragraph"> <p>That code is almost never correct or justified. Just to mention some of its many flaws, we can say:</p> </div> <div class="ulist"> <ul> <li> <p>To create an instance of <code>B</code>, we must allocate first memory to create an instance of <code>A</code>.</p> </li> <li> <p>If a declaration of some type (i.e.: a member variable) in a particular scope (i.e.: the inner class) has the same name as another declaration in the enclosing scope, then the declaration shadows the declaration of the enclosing scope.</p> </li> </ul> </div> <div class="paragraph"> <p>In such cases, the correct approach is to declare a static nested class or interface (<a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.1.1.4" target="_blank" rel="noopener">§8.1.1.4</a>, <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-9.1.1.3" target="_blank" rel="noopener">§9.1.1.3</a>):</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">class A { static class B { } }</code></pre> </div> </div> <div class="paragraph"> <p>Now <code>B</code> no longer "lives within" <code>A</code>, and we can simply use it like this:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">var b = new A.B();</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> <div class="paragraph"> <p>Notice we can’t use <code>static</code> as a class or interface modifier if the class or interface is not a member of another class or interface.</p> </div> <div class="paragraph"> <p>For example, in the previous code snippet, we can’t declare the class <code>A</code> as <code>static</code> or it causes a compilation error.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_static_fields">Static fields</h3> <div class="paragraph"> <p>In a previous article, we saw how to declare <a href="/articles/2024/java-oop-classes-and-objects.html#fields" target="_blank" rel="noopener">fields</a>. To make them <em>static</em> we just need to add the <code>static</code> modifier. Let’s see an example:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">class Payment { static int MAX = 1000; }</code></pre> </div> </div> <div class="paragraph"> <p>In the previous snippet, <code>MAX</code> is a static field. This means it’s not related to any specific instance of <code>Payment</code>. Instead, it is associated with the class where it’s declared.</p> </div> <div class="paragraph"> <p>For example, assuming <code>Payment</code> is located in the same package the following <code>Main</code> class is located, then the <code>MAX</code> field could be used like this:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public class Main { public static void main(String[] args) { System.out.println(Payment.MAX); } }</code></pre> </div> </div> <div class="paragraph"> <p>Notice here, how we didn’t have to <a href="/articles/2024/java-oop-classes-and-objects.html#constructors" target="_blank" rel="noopener">instantiate</a> <code>Payment</code> to access the static field.</p> </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>If we use an object of type <code>Payment</code> to access the static field, Java ignores the object and accesses the static field through the class, that’s it, the instance of the class is only used to know what’s the type that declares the field.</p> </div> <div class="paragraph"> <p>A long time ago, I answered a <a href="https://stackoverflow.com/a/43126188/5640649" target="_blank" rel="noopener">question on StackOverflow</a> where the original poster asked about this, and, despite I learned about it at the time, 6 years later it came back to bite me in a job interview.</p> </div> <div class="paragraph"> <p>When I was asked what the following code would print/do, I hesitated to answer correctly and without any doubts:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">class Order { static int basicPackage = 1; } public class Main { public static void main(String[] args) { Order order = new Order(); System.out.println(order.basicPackage); // prints 1 order = null; System.out.println(order.basicPackage); // prints 1 too } }</code></pre> </div> </div> <div class="paragraph"> <p>I hope you came to the conclusion it prints <code>1</code> twice because the object <code>order</code> is only used in this context by Java to know that this object is of type <code>Order</code> and get the value of the static field from the type itself, instead of getting it from the instance.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>The declaration of a static field (also known as <em>class variable</em>) introduces a static context, which limits the use of constructs that refer to the current object (<a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.3.1.1" target="_blank" rel="noopener">§8.3.1.1</a>). For example, a static field can’t be accessed from an instance method, or the <code>this</code> or <code>super</code> keywords.</p> </div> <div class="paragraph"> <p>This type of construct is useful when declaring constants or variables shared across all instances of a class. That’s because the values of such fields are not associated to a specific instance of a class but rather to the class itself — hence they’re also called <em>class variables</em>.</p> </div> <div class="paragraph"> <p>Because of this behavior, any change made to a static field is reflected everywhere it’s used, regardless whether it’s being accessed from one or another instance of the class that declares it, or even by other classes.</p> </div> <div class="paragraph"> <p>The most common scenario where static fields are used is when combined with the <a href="/articles/2024/the-final-keyword-in-java.html#_final_fields" target="_blank" rel="noopener">final keyword</a> to create inmutable constants that we can use throughout our code. For example:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public class Order { public static final int BASIC_PACKAGE = 1; }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_static_methods">Static methods</h3> <div class="paragraph"> <p>Static methods, just like static fields, are regular <a href="/articles/2024/java-oop-classes-and-objects.html#methods" target="_blank" rel="noopener">methods</a> to which the <code>static</code> modifier have been applied to. Let’s build on top of our previous example:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">class Payment { static int MAX = 1000; static boolean isValidTransactionAmount(int amount) { return amount > 0 && amount <= MAX; } }</code></pre> </div> </div> <div class="paragraph"> <p>Here we’ve declared a method <code>isValidTransactionAmount</code> which is static, that’s it, we don’t need an object of type <code>Payment</code> to use it. For example, this is how we’d call it:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public class Main { public static void main(String[] args) { System.out.println(Payment.isValidTransactionAmount(20)); // prints true } }</code></pre> </div> </div> <div class="paragraph"> <p>Again, static methods involve a static context from where we don’t have access to constructs that refer to the current object, such as instance fields, the <code>this</code> keyword, or the <code>super</code> keyword. That’s only expected.</p> </div> <div class="paragraph"> <p>Static fields and methods are constructed when the class is initialized, not when class instances are constructed, so there’s no way to access those instance constructs.</p> </div> </div> <div class="sect2"> <h3 id="_static_initializers">Static initializers</h3> <div class="paragraph"> <p>Static initializers are almost the same as instance initializers from a syntax perspective. For example, building on top of the previous example, we could initialize the <code>MAX</code> variable like this:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">class Payment { static int MAX; static { MAX = 1000; } }</code></pre> </div> </div> <div class="paragraph"> <p>This construct is useful when the initialization of a static variable is not simple enough to fit in one line. In this example, it’s not worth it, but there are real-world scenarios where there’s some complex logic we want to execute when the class is constructed.</p> </div> <div class="paragraph"> <p>However, this construct should be used carefully because sometimes it’s not easy to reason about the logic being implemented. That’s because the field declaration and the actual initialization are separated.</p> </div> <div class="paragraph"> <p>The same rules about accessing constructs that refer to the current object apply here.</p> </div> <div class="paragraph"> <p>Additionally, there are a few notes we should remember about static initializers (<a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.7" target="_blank" rel="noopener">§8.7</a>):</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>It’s a compile-time error if a static initializer can’t complete normally.</p> </li> <li> <p>It’s a compile-time error if a <code>return</code> statement appears anywhere within a static initializer.</p> </li> <li> <p>For more complex use cases, there are also some exhaustive <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.3.3" target="_blank" rel="noopener">definitions</a> that you should be aware of.</p> </li> </ol> </div> </div> <div class="sect2"> <h3 id="_static_imports">Static imports</h3> <div class="paragraph"> <p>Static imports (<a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-7.html#jls-7.5.3" target="_blank" rel="noopener">§7.5.3</a>) are used to import static-accessible members from other types, such as classes, into a given type, for example, another class.</p> </div> <div class="paragraph"> <p>It works by specifying the <code>static</code> keyword after the <code>import</code> keyword. For example, let’s suppose we have the following <code>Payment</code> class, located in a package named <code>com.payment</code>.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">package com.payment; public class Payment { public static int MAX = 1000; }</code></pre> </div> </div> <div class="paragraph"> <p>If we have another class called <code>Service</code> in a package called <code>com.services</code> and we want to import statically, the <code>MAX</code> static field from <code>Payment</code>, we could do so like this:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">package com.services; import static com.payment.Payment.MAX; class Service { static { System.out.println(MAX); } }</code></pre> </div> </div> <div class="paragraph"> <p>It also works for the wildcard (<code>*</code>) import. This one would import <em>all</em> static members of <code>Payment</code>.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">import static com.payment.Payment.*;</code></pre> </div> </div> <div class="paragraph"> <p>The alternative to this import is the regular import:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">package com.services; import com.payment.Payment; class Service { static { System.out.println(Payment.MAX); } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_additional_considerations">Additional considerations</h2> <div class="sectionbody"> <div class="paragraph"> <p>While static fields and methods allow us to share common attributed and behaviors defined in a class, if not used properly they could cause concurrency issues in multithreaded environments.</p> </div> <div class="paragraph"> <p>For that reason we must use them judiciously and take the appropriate measure to make our data structure thread-safe to avoid data corruption, race conditions, deadlocks and many of the other well-known concurrency challenges we face in software programming.</p> </div> </div> </div> <div class="sect1"> <h2 id="_final_thoughts">Final thoughts</h2> <div class="sectionbody"> <div class="paragraph"> <p>Static constructs offer us the flexibility to go beyond simple object-oriented programming (OOP) designs. With it, we can implement our solutions following a different approach in many cases, including some functional-programming style.</p> </div> <div class="paragraph"> <p>From declaring simple constant fields to building <a href="https://en.wikipedia.org/wiki/Pure_function" target="_blank" rel="noopener">pure functions</a>, the <code>static</code> keyword brings to the Java world the necessary power to be more than just an OOP language. This may seems superfluous, but given the wide adoption Java has had, it’s important to keep the language and platform flexible enough to meet different use cases.</p> </div> <div class="paragraph"> <p>Hopefully, the insights and links shared here are a good reference and a starting point for you to dig deeper into the intricacies and use cases of the <code>static</code> keyword and its constructs, to bring their benefits to your daily coding job; and, as always, be aware of possible pitfalls while using it.</p> </div> </div> </div> asiel@lealceldeiro.com(Asiel Leal Celdeiro) https://lealceldeiro.com/articles/2024/the-final-keyword-in-java.html Thu, 15 Feb 2024 00:00:00 +0000 articles/2024/the-final-keyword-in-java.html <div id="toc" class="toc"> <div id="toctitle">In this article</div> <ul class="sectlevel1"> <li><a href="#_whats_the_final_keyword_in_java">What’s the <code>final</code> keyword in Java?</a></li> <li><a href="#_use_cases_for_the_final_keyword">Use cases for the <code>final</code> keyword</a> <ul class="sectlevel2"> <li><a href="#_final_classes">Final classes</a></li> <li><a href="#_final_fields">Final fields</a></li> <li><a href="#_final_methods">Final methods</a></li> <li><a href="#_final_variables">Final variables</a></li> </ul> </li> <li><a href="#_final_thoughts">Final thoughts</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>The <code>final</code> keyword in Java might seem simple at first glance, but it’s a powerful tool that can significantly impact our code’s design, readability, and performance. In this article, we’ll delve into the different ways we can use <code>final</code> and explore its various benefits for Java developers.</p> </div> </div> </div> <div class="sect1"> <h2 id="_whats_the_final_keyword_in_java">What’s the <code>final</code> keyword in Java?</h2> <div class="sectionbody"> <div class="paragraph"> <p>To put it simple, we say something is <em>final</em> when it can’t be "modified".</p> </div> <div class="paragraph"> <p>Imagine a chick that just hatched out of an egg. That egg is broken, and nothing can revert that; nobody can put together a hatched, or broken, egg, and make the small chick live inside it again, right? It’s the same in Java when something is final. However, technically speaking, the meaning that something can’t be <em>modified</em> takes several forms.</p> </div> <div class="paragraph"> <p>For example, we can use it when we have a variable holding a reference to an <a href="/articles/2024/java-oop-classes-and-objects.html#constructors" target="_blank" rel="noopener">object</a> and we want that variable to keep the same reference throughout the whole program execution. This means no other reference can be assigned to it.</p> </div> <div class="paragraph"> <p>But it can get tricky sometimes. Let’s see it in details.</p> </div> </div> </div> <div class="sect1"> <h2 id="_use_cases_for_the_final_keyword">Use cases for the <code>final</code> keyword</h2> <div class="sectionbody"> <div class="paragraph"> <p>The <code>final</code> keyword can be applied in several scenarios. Let’s analyze them, one by one.</p> </div> <div class="sect2"> <h3 id="_final_classes">Final classes</h3> <div class="paragraph"> <p>To declare a class <em>final</em> we use the <code>final</code> class modifier. For example:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">final class Payment { }</code></pre> </div> </div> <div class="paragraph"> <p>A final class can’t be extended. This means no other class can be a subclass of the <em>final</em> class.</p> </div> <div class="paragraph"> <p>This is useful in situations where we want to limit the inheritance of our type (class), for example, for security reasons. It enforces the intended design and prevents unintended modifications through inheritance.</p> </div> </div> <div class="sect2"> <h3 id="_final_fields">Final fields</h3> <div class="paragraph"> <p>To declare a field <em>final</em>, again we use the same keyword. For example, if we were to add a final field ("amount") to our previous class, this could be it:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">final class Payment { private final BigDecimal amount; Payment(BigDecimal amount) { this.amount = amount; } }</code></pre> </div> </div> <div class="paragraph"> <p>From now on, this field (<code>amount</code>) can’t be assigned a new value, or a compile-time error will be reported and the code will fail to compile.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> <div class="paragraph"> <p><code>final</code> fields could still be modified through other mechanisms such as <a href="https://www.oracle.com/technical-resources/articles/java/javareflection.html" target="_blank" rel="noopener">reflection</a> (<a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-17.html#jls-17.5.3" target="_blank" rel="noopener">§17.5.3</a>), but that’s a more complex topic, better covered in its own article.</p> </div> <div class="paragraph"> <p>It’s also important to have in mind that a <code>final</code> field (or variable, for the matter) holds a reference to an object, and that object can still be mutable regardless. So, it’s possible to mutate the state of the object.</p> </div> <div class="paragraph"> <p>For example, suppose we have a field like this: <code>final Map<String, String> map = new HashMap<>()</code>. If we call <code>map.add("a", "b")</code> we didn’t change the reference which <code>map</code> points to, but we effectively changed the value of <code>map</code> by adding a new entry.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>In the previous <code>Payment</code> class example, notice, how we had to declare our own constructor to accept a value for our <code>amount</code> field. This is because all final instance fields must be initialized when the class instance is created. In the case of the static ones, they must be initialized when the class is loaded.</p> </div> <div class="paragraph"> <p>Other ways to initialize final fields are as follows:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>On the same line where the field is declared. For example:</p> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">final class Payment { private static final BigDecimal MAX_ALLOWED = new BigDecimal(1000_000); private final BigDecimal amount = new BigDecimal(100); }</code></pre> </div> </div> </li> <li> <p>Inside an instance, or static initializer, respectively. For example:</p> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">final class Payment { private static final BigDecimal MAX_ALLOWED; private final BigDecimal amount; static { MAX_ALLOWED = new BigDecimal(1000_000); } { amount = new BigDecimal(100); } }</code></pre> </div> </div> </li> <li> <p>For the sake of completeness, let’s mention here the third option: inside the class constructor (as we saw previously).</p> </li> </ol> </div> <div class="paragraph"> <p>Final fields give us the big benefit of thread safety (<a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-17.html#jls-17.5" target="_blank" rel="noopener">§17.5</a>). This doesn’t mean that if we declare all fields as <code>final</code> in a class that will make the class thread safe; but it’s one of the actions we can take towards that goal, and it’s a simple one.</p> </div> <div class="paragraph"> <p>It brings also with it more predictable and easy-to-reason-about code and the JVM can also perform low-level optimization over those fields because of their final nature.</p> </div> <div class="paragraph"> <p>One common scenario where final fields are used is when combined with the <a href="/articles/2024/the-static-keyword-in-java.html#_static_fields" target="_blank" rel="noopener">static keyword</a> to create inmutable constants that we can use throughout our code.</p> </div> </div> <div class="sect2"> <h3 id="_final_methods">Final methods</h3> <div class="paragraph"> <p>To declare a final method we use the same <code>final</code> keyword. For example:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">class Payment { private final BigDecimal amount = new BigDecimal(100); final BigDecimal getAmount() { return amount; } }</code></pre> </div> </div> <div class="paragraph"> <p>In this previous example the <code>Payment</code> class is not <code>final</code>. This means it can be subclassed and its methods overridden or hidden in the children classes (<a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.4.3.3" target="_blank" rel="noopener">§8.4.3.3</a>). One way to avoid that is to declare those methods as <code>final</code>.</p> </div> <div class="paragraph"> <p>This is a powerful technique: it permits that we have a class that can be extended but certain public behaviors of it can’t be changed, not even by its subclasses. This keeps the parent class maintainers in control, and avoid unexpected bugs.</p> </div> </div> <div class="sect2"> <h3 id="_final_variables">Final variables</h3> <div class="paragraph"> <p>Final variables are also declared by using the same <code>final</code> keyword. For example, in the following method, the argument <code>id</code> and the local variable <code>transaction</code> are final.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">class Payment { void executeTransaction(final Long id) { final Transaction transaction = getCurrentTransaction(); // rest of the code omitted for brevity } }</code></pre> </div> </div> <div class="paragraph"> <p>Something to note here is that if we declare a variable without the <code>final</code> keyword, and it’s never modified again, then it’s <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-4.html#jls-4.12.4" target="_blank" rel="noopener"><em>effectively final</em></a>.</p> </div> <div class="paragraph"> <p>The use cases for final variables range from code standards and best practices established in some companies, to language requirements such as lambda expressions. Let’s analyze this last one.</p> </div> <div class="paragraph"> <p><a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-15.html#jls-15.27" target="_blank" rel="noopener">Lambda expressions</a> require that any local variable, formal parameter, or exception parameter used but not declared in a lambda expression must either be final or effectively final (<a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-15.html#jls-15.27.2" target="_blank" rel="noopener">§15.27.2</a>).</p> </div> <div class="paragraph"> <p>Let’s take as an example the following code:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">class Payment { void executeTransaction(Long id) { Transaction transaction = getTransaction(); queueTasks(() -> System.out.printf("Queued tasks for transaction %s and id %s", transaction, id)); } Transaction getTransaction() { return new Transaction(); } void queueTasks(Runnable callback) { // code omitted for brevity callback.run(); } } class Transaction {}</code></pre> </div> </div> <div class="paragraph"> <p>For the sake of simplicity, let’s focus only on the method <code>executeTransaction</code> (and ignore the auxiliary methods).</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">void executeTransaction(Long id) { Transaction transaction = getTransaction(); queueTasks(() -> System.out.printf("Queued tasks for transaction %s and id %s", transaction, id)); }</code></pre> </div> </div> <div class="paragraph"> <p>In its body, there’s a call to <code>queueTasks</code> which accepts a <code>Runnable</code> parameter. Because <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Runnable.html" class="link-underline link-underline-opacity-0" target="_blank" rel="noopener"><code>Runnable</code></a> is a <a href="https://docs.oracle.com/javase/8/docs/api/java/util/function/package-summary.html" target="_blank" rel="noopener">functional interface</a> we can provide the argument as a lambda expression.</p> </div> <div class="paragraph"> <p>In the body of the lambda expression the variable <code>transaction</code> and the parameter <code>id</code> are used without being declared <code>final</code> explicitly. This is possible because they are <em>effectively final</em>.</p> </div> <div class="paragraph"> <p>If we were to re-assign a new value to either <code>transaction</code> or <code>id</code> then they would stop being effectively final. This would cause a compile-time error reported when either of them is first accessed inside the lambda body. The message would say something like <code>Variable used in lambda expression should be final or effectively final</code>.</p> </div> <div class="paragraph"> <p>To avoid such error, we can declare them as <code>final</code> and, if we ever re-assign a new value to them, we get a compile-time error on the line where the re-assignment happens.</p> </div> <div class="paragraph"> <p>Declaring <code>final</code> variables is also useful in scenarios where there are many variables declared (common in long methods from legacy code), and we want to make sure none of them is re-assigned a new value.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_final_thoughts">Final thoughts</h2> <div class="sectionbody"> <div class="paragraph"> <p>Now that we’ve explored what’s the <code>final</code> keyword used for and how to apply it, it’s time for you to put that knowledge to work on your daily job.</p> </div> <div class="paragraph"> <p>Look again that class design and ask yourself: Is this class supposed to be subclassed? If yes, then document it, if not, then make it final. Your future self will thank you. You can always come back and make the class non-final, but you can’t make a class final without possibly breaking other code that could have extended your class (<a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-13.html#jls-13.4.2.3" target="_blank" rel="noopener">§13.4.2.3</a>).</p> </div> <div class="paragraph"> <p>Questions like this should pop out of your mind when you design and implement your solutions. It will help with the overall code quality and the quality of the final product, which means happier final users.</p> </div> <div class="paragraph"> <p>One final word of <strong>caution</strong>.</p> </div> <div class="paragraph"> <p>With great power comes great responsibility. While <code>final</code> is powerful, its overuse can lead to inflexible code. We should use it judiciously, considering the trade-offs between immutability and flexibility and striving to achieve the correct balance.</p> </div> </div> </div> asiel@lealceldeiro.com(Asiel Leal Celdeiro) https://lealceldeiro.com/articles/2024/sealed-classes-in-java.html Mon, 5 Feb 2024 00:00:00 +0000 articles/2024/sealed-classes-in-java.html <h2 id="what-are-sealed-classes-in-java">What are sealed classes in Java?</h2> <p> In a <a href="/articles/2024/java-oop-classes-and-objects.html" target="_blank">previous article</a> we learned what's a Java class. From a code perspective, sealed classes are not far from a regular class, but they're somehow special in the way they can be extended. Let's see it in details. </p> <h3 id="sealed-keyword">The <code>sealed</code> keyword</h3> <p> In the aforementioned post there's a reference to a <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-ClassModifier" target="_blank" class="link-underline link-underline-opacity-0"> class modifier </a> called <code>sealed</code>. This is the differentiator, from a code perspective, of a sealed class from a regular class. </p> <p> A class is sealed when this keyword is used in its declaration. More formally, it's a class of which all direct subclasses are known when it's declared, and no other direct subclasses are desired or required ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.1.1.2" target="_blank"> §8.1.1.2 </a>). So, its declaration is the same we <a href="/articles/2024/java-oop-classes-and-objects.html#structure" target="_blank">saw already</a>, with the specificity that <code>sealed</code> must be present as a class modifier: </p> <pre><code class="language-java"> {ClassModifier} class TypeIdentifier [TypeParameters] [ClassExtends] [ClassImplements] [ClassPermits] ClassBody </code></pre> <p>Let's see an example:</p> <pre><code class="language-java"> sealed class PrimaryColor { } </code></pre> <h2 id="uses-of-sealed-classes">Use cases for sealed classes</h2> <p> Sealed classes, being a <a href="https://openjdk.org/jeps/409" target="_blank">relatively new addition</a> to Java, have enabled developers to use some features and paradigms more easily. For example, they, together with <a href="https://docs.oracle.com/en/java/javase/21/language/records.html#GUID-6699E26F-4A9B-4393-A08B-1E47D4B2D263" target="_blank"> records </a>, and <a href="https://docs.oracle.com/en/java/javase/21/language/pattern-matching-switch-expressions-and-statements.html#GUID-E69EEA63-E204-41B4-AA7F-D58B26A3B232" target="_blank"> pattern matching </a>, have made much easier to write our code following a <a href="https://www.infoq.com/articles/data-oriented-programming-java/" target="_blank"> data-oriented programming </a> approach. </p> <p> I would say this is one of the cases where they fit the best: they allow us to represent in our code the real-world data structures more accurately in scenarios where inheritance is needed, but limited to only just some known subtypes, and where, therefore, "traditional" inheritance is not a perfect fit. </p> <p> This means with sealed classes we can create <em>closed type hierarchies</em>, <em>limited set of implementations</em>, <em>state machines</em>, <em>limited set of exceptions</em>, and more, everything revolving around the main capability of limiting the number of subtypes that can be defined for a given class or interface. </p> <p> This explicit and exhaustive control over the direct subtypes is useful when the class hierarchy is used to model the types of values in a domain, rather than as a mechanism for code inheritance and reuse. </p> <h2 id="sealed-classes-example">Example</h2> <p> Let's consider the previous class, <code>PrimaryColor</code>; it represents a primary color (concept from our real-world business domain). For the sake of simplicity, let's assume red, yellow, and blue are the only possible primary colors in our business domain <a href="#primaryColorsFootNote" target="_blank" class=" link-underline link-underline-opacity-0"><sup>1</sup></a>. </p> <p> This naturally leads us to want to have a superclass <code>PrimaryColor</code> and only three subclases: <code>Red</code>, <code>Yellow</code>, and <code>Blue</code>. With this setup we have the data structure that represents our data, modeled as Java classes/objects. Before sealed classes came along, the code would have looked like this: </p> <pre><code class="language-java"> class PrimaryColor { } class Red extends PrimaryColor { } class Yellow extends PrimaryColor { } class Blue extends PrimaryColor { } </code></pre> <p> Then other developers could use these classes to interact with our <a href="/articles/2024/java-interfaces.html" target="_blank">API</a>. Maybe they need to send a piece of data, packed as one of these three classes. Something like this: </p> <pre><code class="language-java"> PrimaryColor color = new Red(); api.send(color); // details of the `api` object are omitted here for brevity </code></pre> <p> That's what we were used to. It represents perfectly our business domain — well, almost. There's one design flaw: we're assuming only <em>red</em>, <em>yellow</em>, and <em>blue</em> could be sent as possible values through our <code>api</code> object, but that's not entirely true. </p> <p> If other developers decide to extend our <code>PrimaryColor</code> class, or any of its subtypes, with a class of their own, they could send any other color, for example <code>Pink</code> which is not <em>primary</em>. They could even send an object <code>apple</code>, which is not a color, but a fruit! </p> <p> So, how do we guarantee that only the specific classes we supply as possible values for <em>primary colors</em> are used? The answer lies in <em>sealed classes</em>. To be fair, there could be other options such as using the <code>instanceof</code> operator, but they're not as clean as using a sealed class, that's why I won't even show the code with that alternative. </p> <p> Back to sealed classes, let's remodel, our code to use this feature: </p> <pre><code class="language-java"> sealed class PrimaryColor { } final class Red extends PrimaryColor { } final class Yellow extends PrimaryColor { } final class Blue extends PrimaryColor { } </code></pre> <p> Notice how <code>PrimaryColor</code> was declared <code>sealed</code> and its subclasses were declared <code>final</code>. This is an improvement. <code>Red</code>, <code>Yellow</code>, and <code>Blue</code> cannot be further extended; and we're showing intent: anyone reading the code will realize we're trying to limit the possible subclasses our <code>PrimaryColor</code> can have. </p> <p> Sadly, good intentions are not enough. Despite declaring a class as <code>sealed</code> and the subclasses <code>final</code>, other classes out of our control could still extend the superclass and be provided as a valid <code>PrimaryColor</code> value. For example, this is valid: </p> <pre><code class="language-java"> // somewhere, in an external code final class Pink extends PrimaryColor { } </code></pre> <p> To fix this, we need to use another keyword in combination with <code>sealed</code>. </p> <h3 id="permits-keyword">The <code>permits</code> keyword</h3> <p> The <em>permits</em> clause specifies all the classes intended as direct subclasses of the class being declared (<a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.1.6" target="_blank">§8.1.6</a>) and its structure is as follows: </p> <pre><code class="language-java"> permits TypeName {, TypeName} </code></pre> <p> This means that any other class that is declared to extend our superclass and which is not present in the superclass' <em>permit</em> clause will receive a compile-time error. </p> <p>Let's revise our previous code to specify the permitted classes:</p> <pre><code class="language-java"> sealed class PrimaryColor permits Blue, Red, Yellow { } final class Red extends PrimaryColor { } final class Yellow extends PrimaryColor { } final class Blue extends PrimaryColor { } </code></pre> <p> By doing this there's no way anyone can extend <code>PrimaryColor</code> further (without us allowing it first in the superclass declaration itself). </p> <p> After this change, the class declaration for <code>Pink</code> would fail and no object of that type can be sent where a <code>PrimaryColor</code> is expected. </p> <h2 id="sealed-classes-considerations">Considerations</h2> <p> There are some important aspects to keep in mind when working with sealed classes: </p> <ul> <li> Interfaces can be declared <code>sealed</code> as well — as you already might have inferred from previous mentions to this. </li> <li> A class/interface cannot be declared <code>sealed</code> without the <em>permits</em> clause and without another class/interface implementing/extending it. So, for example, this code alone will report a compile-time error: <pre><code class="language-java"> sealed interface Processor { } </code></pre> To make it compile we could have a class to implement it — something like this: <pre><code class="language-java"> final class OrderProcessor implements Processor { } </code></pre> </li> <li> A class is said to be <em>freely extensible</em> if its direct superclass is not <code>sealed</code>, and none of its direct superinterfaces are <code>sealed</code>, and it's neither <code>sealed</code> nor <code>final</code> itself. Otherwise, such a class is freely extensive if and only if it is declared <code>non-sealed</code> (and is not <code>final</code>, of course). </li> <li> Related to the previous point, if a class has a <code>sealed</code> direct superclass or a <code>sealed</code> direct superinterface, it's a compilation error if such class is not declared <code>final</code>, <code>sealed</code>, or <code>non-sealed</code>, either explicitly or implicitly; that's because when a class is declared <code>sealed</code>, it forces all direct subclasses to explicitly declare whether they are <code>final</code>, <code>sealed</code>, or <code>non-sealed</code>. </li> <li> Enums are either <em>implicitly</em> <code>final</code> or <em>implicitly</em> <code>sealed</code>, so they can implement a sealed interface. Similarly, a record class is <em>implicitly</em> <code>final</code>, so it can also implement a sealed interface. </li> <li> A class can not be declared <code>non-sealed</code>, unless it has either a sealed direct superclass or a sealed direct superinterface — otherwise a compilation error is reported. </li> <li> The <em>permits</em> clause cannot be used without the <code>sealed</code> modifier in the type declaration. </li> <li> Every permitted direct subclass specified by the <em>permits</em> clause must be a direct subclass of the superclass or a compile-time error occurs. </li> <li> Every type listed in the <em>permits</em> clause must be accessible at compile-time and must be specified only once, otherwise the code won't compile. </li> <li> If a sealed class <code>C</code> is associated with a named module ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-7.html#jls-7.3" target="_blank"> §7.3 </a>) , then every class specified in the permits clause of <code>C</code>'s declaration must be associated with the same module as <code>C</code>, or a compile-time error is reported (<a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.1.6" target="_blank">§8.1.6</a>). This makes perfect sense, as supertypes and subtypes must be <em>resolvable</em>/accessible during compile-time and for this to be 100% guaranteed, they must be located in the same module (in modular systems). Also, any class hierarchy structure should be declared in the same business domain unit (module), where maintenance is provided by the same development team. </li> </ul> <h2>Sealed classes without permitted subtypes</h2> <p> Strictly speaking, a class or interface can be declared <code>sealed</code> without declaring the permitted subtypes, as long as the above considerations are taken into account. When this happens, the permitted subtypes are automatically inferred to those which are direct subtypes. </p> <p> Care must be taken if this approach is used: sealed classes are usually intended to restrict a type hierarchy. If we don't explicitly list the possible subtypes by using the <em>permits</em> clause, then in future other subtypes can be added with unintended consequences, such as getting a compile-time error on a <code>switch</code> case because it's non-exhaustive anymore. </p> <p></p> <h2 id="sealed-classes-final-thoughts">Final thoughts</h2> <p> Sealed classes are yet another great improvement to the Java language and platform, that gives developers more options to build secure robust and predictable software. It specifically allows us to model different kinds of a business domain in our code with precision and without resorting to weird workarounds or twisted class hierarchies. </p> <p> Together with other language constructs, sealed classes, enhance our code and make it more succinct, readable, and maintainable, which leads towards more productive teams. If this articles doesn't cover everything about sealed classes, it is a good start for you to read and investigate more about this topic so you can put it in practice in your day-to-day job. </p> <hr/> <p id="primaryColorsFootNote"> <sup><a href="https://en.wikipedia.org/wiki/Primary_color" target="_blank">1</a></sup> The <a href="https://en.wikipedia.org/wiki/Primary_color" target="_blank"> colors system</a> is complex. This post doesn't attempt to explain it in details. It doesn't either affirm that read, yellow, and blue are <strong>the</strong> primary colors. </p> asiel@lealceldeiro.com(Asiel Leal Celdeiro) https://lealceldeiro.com/articles/2024/abstrat-classes-in-java.html Sun, 28 Jan 2024 00:00:00 +0000 articles/2024/abstrat-classes-in-java.html <h2 id="what-are-abstract-classes-in-java">What are abstract classes in Java?</h2> <p> In a <a href="/articles/2024/java-oop-classes-and-objects.html" target="_blank">previous post</a> we learned what's a Java class. To be more precise, the examples mentioned there are <em>concrete</em> classes. Usually, when there's no mention whether a class is concrete or abstract, it's inferred we're talking about a concrete class. Likewise, if we want to talk about an abstract one, we usually make the distinction by saying <em>... an abstract class...</em>. </p> <p> So, then, when is a class abstract? </p> <h2 id="abstract-class-keyword">The <code>abstract</code> keyword</h2> <p> A class is abstract when the <code>abstract</code> keyword ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-ClassModifier" target="_blank" class="link-underline link-underline-opacity-0"> ClassModifier </a>) is used in the class declaration. It is a class that is incomplete, or to be considered incomplete ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.1.1.1" target="_blank"> §8.1.1.1 </a>). Hence, the syntax for the full declaration of an abstract class is the same we <a href="/articles/2024/java-oop-classes-and-objects.html#structure" target="_blank">saw already</a>: </p> <pre><code class="language-java"> {ClassModifier} class TypeIdentifier [TypeParameters] [ClassExtends] [ClassImplements] [ClassPermits] ClassBody </code></pre> <p>Let's see an example</p> <pre><code class="language-java"> abstract class Animal { } </code></pre> <h2 id="abstract-classes-abstract-methods">Abstract methods</h2> <p> Ok, the code looks simple. By just adding <code>abstract</code> to our class declaration we made it abstract. But what's so especial about it? </p> <p> Well, when a class is abstract we can declare abstract methods in its <a href="/articles/2024/java-oop-classes-and-objects.html#class-body" target="_blank">body</a>. An abstract method is a method without a body (no implementation). Then, subclasses that extend the abstract class must provide concrete implementations for these abstract methods. For example: </p> <pre><code class="language-java"> abstract class Animal { abstract void move(); } </code></pre> <h2 id="uses-of-abstract-classes">Use cases for abstract classes</h2> <p> Before seeing some elaborated examples, let's understand this: why would we want to declare an abstract class to begin with? </p> <p> Let's recap: we use classes to model our domain, our real world entities and concepts as well as their interactions with each other. And, as you might guess, some of those concept and entities are represented in our minds as abstract ones. </p> <p> For example: if we're modeling a software for a Zoo, we need to model animals, the staff, food, cages, etc. Some of these concepts need to be modeled at a higher level of abstraction to represent them properly. Imagine we want to have a class <code>Tiger</code> to handle information about tigers, <code>Snake</code> to handle information about the snakes in the Zoo, <code>Crocodile</code>, <code>Parrot</code>, ... you get the idea. </p> <p> All of these animals have many things in common; for example, they all move, they eat, they breathe, and so on. But they also have many differences: some of them walk, some crawl, some fly, etc. </p> <p> It's exactly because of their differences that we need to create separate classes for each of them —that's clear—. But this leaves us with a problem, what do we do with the things ( <a href="/articles/2024/java-oop-classes-and-objects.html#fields" target="_blank">properties</a> and <a href="/articles/2024/java-oop-classes-and-objects.html#methods" target="_blank">behaviors</a>) they share? Do we just duplicate those fields and methods in each class? That doesn't sound good. Let's see an example of how it would look like: </p> <pre><code class="language-java"> class Tiger { String name; int energy; Tiger(String name) { this.name = name; energy = 100; } void move() { energy -= 3; System.out.println(name + " walked"); } void eat() { energy++; System.out.println(name + " ate"); } } class Snake { String name; int energy; Snake(String name) { this.name = name; energy = 100; } void move() { energy -= 2; System.out.println(name + " crawled"); } void eat() { energy++; System.out.println(name + " ate"); } } class Parrot { String name; int energy; Parrot(String name) { this.name = name; energy = 100; } void move() { energy--; System.out.println(name + " flew"); } void eat() { energy++; System.out.println(name + " ate"); } } </code></pre> <p> There's a LOT of duplication in that code! Actually, everything, except for the <code>move</code> method is the same. This design is difficult to maintain at a bigger scale. Imagine a production code base with hundreds of classes and several team members working simultaneously on it. That's not how we should design it for the long term. </p> <p> This is one of the scenarios where abstract classes shine. They allow us to represent abstract concepts and "delegate" the specificities to the concrete classes that implement them. </p> <h2 id="examples">Example</h2> <p> Let's refactor the previous code to use an abstract class to keep the same fields and methods in it and delegate the specifics of each animal to the subclasses. </p> <pre><code class="language-java"> abstract class Animal { String name; int energy; Animal(String name) { this.name = name; energy = 100; } abstract void move(); void eat() { energy++; System.out.println(name + " ate"); } } class Tiger extends Animal { Tiger(String name) { super(name); } @Override void move() { energy -= 3; System.out.println(name + " walked"); } } class Snake extends Animal { Snake(String name) { super(name); } @Override void move() { energy -= 2; System.out.println(name + " crawled"); } } class Parrot extends Animal { Parrot(String name) { super(name); } @Override void move() { energy--; System.out.println(name + " flew"); } } </code></pre> <p> Now, this is better. Now we can see clearly what fields and methods belong to an <em><code>Animal</code></em>. Everything else belongs to the details of specific classes (<code>Tiger</code>, <code>Parrot</code>, etc.) </p> <blockquote> Notice in the previous code snippet we've used the <a href="/articles/2024/java-annotation-interfaces.html#interface-examples" target="_blank"> <code>@Override</code> annotation </a> to make sure we're overriding properly the <code>move</code> method. </blockquote> <h2 id="instantiation">Instantiation</h2> <p> Now we can use the abstract class and its subclasses in our code, but, because abstract classes cannot be instantiated directly by using the <code>new</code> keyword (see next section), we need to create objects of the concrete subclasses and use them polymorphically. </p> <pre><code class="language-java"> public static void main(String[] args) { Animal teo = new Tiger("Teo"); Animal sisi = new Snake("Sisi"); Animal pepi = new Parrot("Pepi"); teo.move(); teo.eat(); sisi.move(); sisi.eat(); pepi.move(); pepi.eat(); } </code></pre> <p>This will print in console:</p> <pre><code class="language-shell"> Teo walked Teo ate Sisi crawled Sisi ate Pepi flew Pepi ate </code></pre> <p> No matter all the objects (<code>teo</code>, <code>sisi</code>, <code>pepi</code>) are stored in a variable (reference) of type <code>Animal</code>, their specific types are different at runtime (such as <code>Tiger</code>) and so their behaviors are different (different texts printed in console). </p> <h2>Considerations</h2> <p> With abstract classes (and <a href="/articles/2024/java-interfaces.html" target="_blank">interfaces</a>) we can simplify complex concepts in the software by modeling these classes based on the real-world concepts we're representing. We could talk infinitely about many of the advantages of this design. Some of the most remarkable ones are: </p> <ul> <li>It ensures consistent behavior and at the same time it permits various implementations</li> <li>Data can now be encapsulated more easily in each class, separately</li> <li>Clear separation of boundaries, concerns and responsibilities of each class</li> <li>More cohesive data structure, without unnecessary code duplication</li> <li>Classes focused on "doing one thing well" — without bloating their code</li> <li>Code base easier to maintain, adapt and scale</li> </ul> <p> However, they're not a silver bullet, we must use them responsibly and have in mind what's their purpose and the problem they solve: </p> <ul> <li> Abstract classes can also have regular (concrete) methods with a complete implementation. These methods can be inherited by the subclasses without any need for overriding. </li> <li> It is a compile-time error if an attempt is made to create an instance of an abstract class using a class instance creation expression ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-15.html#jls-15.9.1" target="_blank"> §15.9.1 </a>). For example, the following code would report a compilation error: <pre><code class="language-java"> Animal animal = new Animal("Teo"); < -- compilation error! </code></pre> The closest we can get the previous code is to use an anonymous class — but this is something completely different from what we're discussing here. Let's see it, for the sake of completeness: <pre><code class="language-java"> Animal animal = new Animal("Tiger") { @Override void move() { energy -=5; System.out.println(name + " moved in an 'anonymous' way"); } }; </code></pre> </li> <li> We can not declare <code>abstract</code> methods in a non-<code>abstract</code> class ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.1.1.1" target="_blank"> §8.1.1.1 </a>). </li> <li> Every constructor of a class extending an abstract class must call (directly, or indirectly) the constructor of the abstract class. In our previous example this corresponds to the line <code>super(name);</code>. </li> <li> <code>abstract</code> methods are inherited. This means if a class inherits some abstract method, that class must either: implement the method (override it), or the class itself must be declared <code>abstract</code> as well. This case would be useful if we want to represent another level of abstraction. For example, if we'd want to model in our software some different types of animal, such as <a href="https://en.wikipedia.org/wiki/Mammal" target="_blank"><em>mammals</em></a>, <a href="https://en.wikipedia.org/wiki/Reptile" target="_blank"><em>reptiles</em></a>, <a href="https://en.wikipedia.org/wiki/Oviparity" target="_blank"><em>oviparous</em></a>, etc., we could create abstract classes for each of them. It would look like this: <pre><code class="language-java"> abstract class Mammal extends Animal { } // ... other classes follow the same pattern </code></pre> </li> <li> Speaking of <em>levels</em> of abstraction; we should avoid creating too many levels of abstractions as then our code can become hard to reason about and difficult to maintain in the long term. </li> <li> Abstract classes should be used when the business domain really demands it. We should not use them just because they give us a "free" pass to "code re-use". If we don't follow this recommendation we can end up with a lot of <a href="https://en.wikipedia.org/wiki/No_Silver_Bullet" target="_blank">accidental complexity</a>. </li> <li> Similarly, abstract classes should not be used with the purpose of preventing its instantiation. If that's the goal, then the correct way of doing it is to declare a constructor for that class and make it <code>private</code> ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.8.10" target="_blank"> §8.8.10 </a>). </li> </ul> <h2 id="abstract-classes-final-thoughts">Final thoughts</h2> <p> Abstract classes represent a powerful tool at our disposal when following the OOP paradigm. Properly implemented, they enhance our code and make it more robust, secure, maintainable and profitable (why not?) in the long term. This article is by no means a complete guide to this topic, and there's much more you can review on your own; but hopefully this is a good start for you to dive deeper into the documentation and information linked here. </p> asiel@lealceldeiro.com(Asiel Leal Celdeiro) https://lealceldeiro.com/articles/2024/java-annotation-interfaces.html Sat, 20 Jan 2024 00:00:00 +0000 articles/2024/java-annotation-interfaces.html <h2 id="what-s-a-java-interface">What's a Java annotation interface?</h2> <p> In a <a href="java-interfaces.html" target="_blank">previous article</a> we learned about normal interfaces. This begs the question, then, what's a Java annotation interface? </p> <p> An <em>annotation interface</em> ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-9.6" target="_blank" class="link-underline link-underline-opacity-0"> §9.6 </a>) is an interface declared with a distinct syntax, intended to be implemented by reflective representations of <em>annotations</em> ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-9.7" target="_blank" class="link-underline link-underline-opacity-0"> §9.7 </a>). </p> <p> We can say that it's a specialized kind of interface and to differentiate it from a normal interface, the keyword <code>interface</code> is preceded by an at sign (<code>@</code>). For example: </p> <pre><code class="language-java"> @interface TraceableMethod { } </code></pre> <p> Once we have declared (or imported) an annotation interface in our code, we can use it to augment our application, for example, to enhance the Java type system with nullability information. An example of this is Spring's <a href="https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/lang/NonNull.html" target="_blank" class="link-underline link-underline-opacity-0"> <code>@NonNull</code> </a> annotation. </p> <p> In this sense, annotations can be used as well with static code analysis tools to detect possible bugs in our code in an early stage and increase productivity in general by avoiding common mistakes in our code and focus in our business logic. </p> <h2 id="syntax">Syntax</h2> <p> From the previous example you're probably already inferring the syntax of this type of interfaces. Let's see it: </p> <pre><code class="language-java"> {InterfaceModifier} @ interface TypeIdentifier AnnotationInterfaceBody </code></pre> <p>Where</p> <ul> <li> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-InterfaceModifier" target="_blank" class="link-underline link-underline-opacity-0"> <code>{InterfaceModifier}</code> </a> is one of: <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-Annotation" target="_blank" class="link-underline link-underline-opacity-0"> <code>Annotation</code> </a>, <code>public</code>, <code>protected</code>, <code>private</code>, <code>abstract</code>, <code>static</code>, <code>sealed</code>, <code>non-sealed</code>, <code>strictfp</code>. </li> <li> <code>@</code> is the special sing used to indicate that this is an annotation interface declaration, and not a normal interface declaration. </li> <li><code>interface</code> is the Java keyword used to specify we're declaring an interface.</li> <li> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-3.html#jls-TypeIdentifier" target="_blank" class="link-underline link-underline-opacity-0"> <code>TypeIdentifier</code> </a> is the name we want to give the annotation. In our previous example we used <code>TraceableMethod</code>. </li> <li> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-AnnotationInterfaceBody" target="_blank" class="link-underline link-underline-opacity-0"> <code>AnnotationInterfaceBody</code> </a> is the <code>body</code> of our annotation, including the curly braces (<code>{}</code>). See next section. </li> </ul> <h3 id="syntax-body">Body</h3> <p> The structure of the body of an annotation interface ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-AnnotationInterfaceMemberDeclaration" target="_blank" class="link-underline link-underline-opacity-0"> AnnotationInterfaceMemberDeclaration </a>) is as follows: </p> <pre><code class="language-java"> { AnnotationInterfaceElementDeclaration ConstantDeclaration ClassDeclaration InterfaceDeclaration } </code></pre> <p> Let's analyze <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-AnnotationInterfaceElementDeclaration" target="_blank" class="link-underline link-underline-opacity-0"> AnnotationInterfaceElementDeclaration </a>. The rest of the elements follow the same <sup>1</sup> rules as those described in <a href="java-interfaces.html#interface-body" target="_blank">normal interface declarations</a>. </p> <h4 id="elements">Annotation interface elements</h4> <p> Annotations (like classes and interfaces) can have attributes. The difference is that they look like methods in the annotation body, even though they're used as normal attributes where the annotation is used. Let's see an example to get a better idea. </p> <pre><code class="language-java"> @interface TraceableMethod { public String traceName() default "TracedMethod"; } </code></pre> <p> Here, we've defined an attribute (the method-like syntax) in the annotation declaration called <code>traceName</code>. Notice how the syntax is somehow the same but different from fields declared in normal interfaces and classes. For example, the modifier (<code>public</code>), the type (<code>String</code>), and the identifier (<code>traceName</code>) are specified similar to how they'd be specified in a class or interface, but then we have the parenthesis (<code>()</code>) and the <code>default</code> keyword used after it, along the actual attribute default value (<code>"TracedMethod"</code>). </p> <h2 id="how-to-use-the-annotation">How to use annotations?</h2> <p> Once the annotation is created (through the annotation interface declaration) it can be placed on classes, methods, fields, and a few other places, and it must appear immediately before what's being annotated. For example, let's suppose we have the following class. </p> <pre><code class="language-java"> class Processor { void process() { } String getName() { return "processor"; } } </code></pre> <p> Now, let's suppose that the goal of the annotation we just declared (<code>TraceableMethod</code>) is, given a class, to "mark" the methods in that class whose names we want to print when our program starts up. For this to happen we must do two things: first, <em>annotate</em> the methods, and second, when our program starts up, "scan" our code and find these methods <em>annotated</em> as <code>TraceableMethod</code>. Let's see it. </p> <h3 id="annotating-an-element">Annotate the methods</h3> <p>For now, we're going to annotate only the <code>process</code> method.</p> <pre><code class="language-java"> class Processor { @TraceableMethod void process() { } String getName() { return "processor"; } } </code></pre> <h3 id="find-elements-annotate-in-our-code">Find the methods annotated in our code</h3> <pre><code class="language-java"> public static void main(String[] args) { Class<?> clazz = Processor.class; Method[] methods = clazz.getDeclaredMethods(); for (Method method : methods) { for (Annotation annotation : method.getAnnotations()) { if (annotation instanceof TraceableMethod traceableMethodAnnotation) { System.out.printf(""" Method %s annotated as %s - trace name: %s """, method.getName(), TraceableMethod.class.getSimpleName(), traceableMethodAnnotation.traceName()); } } } } </code></pre> <p> If you run this example you'll see an empty output. That's because we did not specify the <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/annotation/RetentionPolicy.html" target="_blank"> retention policy </a> of the annotation. </p> <p>There are three values we can use here:</p> <ul> <li> <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/annotation/RetentionPolicy.html#CLASS" target="_blank" class="link-underline link-underline-opacity-0"> <code>CLASS</code> </a> (keep the annotation after the code is compiled but ignored by the JVM during runtime) </li> <li> <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/annotation/RetentionPolicy.html#RUNTIME" target="_blank" class="link-underline link-underline-opacity-0"> <code>RUNTIME</code> </a> (keep the annotation after the code is compiled and by the JVM during runtime) </li> <li> <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/annotation/RetentionPolicy.html#SOURCE" target="_blank" class="link-underline link-underline-opacity-0"> <code>SOURCE</code> </a> (discard the annotation by the compiler) </li> </ul> <p> So, because <code>CLASS</code> is the default retention policy our annotation was kept after compilation, but during runtime, it was not taken into account by the JVM, hence the call to <code>method.getAnnotations()</code> returned an empty array. How do we fix it? We change the retention policy... by using a meta-annotation! </p> <pre><code class="language-java"> @Retention(RetentionPolicy.RUNTIME) @interface TraceableMethod { public String traceName() default "TracedMethod"; } </code></pre> <p> Now, if you run the same code again you'll se the following output: </p> <pre><code class="language-shell"> Method process annotated as TraceableMethod - trace name: TracedMethod </code></pre> <h3 id="specifying-attributes">Specifying annotation attributes</h3> <p> What about the field <code>traceName</code> declared in the body of the annotation? From the previous output we can see it took the default value (<code>TracedMethod</code>); but what if we want to change it. Simple, we can specify it within parenthesis (<code>()</code>) after the annotation name. </p> <p> Let's annotate the method <code>getName</code>, in <code>Processor</code>, and let's specify for it a different <code>traceName</code> value. </p> <pre><code class="language-java"> class Processor { @TraceableMethod void process() { } @TraceableMethod(traceName = "String returning method") String getName() { return "processor"; } } </code></pre> <p> When we run again the code, now this is the output: </p> <pre><code class="language-shell"> Method getName annotated as TraceableMethod - trace name: String returning method Method process annotated as TraceableMethod - trace name: TracedMethod </code></pre> <p> As you see here, now the method <code>getName</code> is reported with a <code>traceName</code> value different from the default one, that's it, <code>String returning method</code>. </p> <h2 id="interface-examples">Example: Using the <code>@Override</code> annotation</h2> <p> The previous example is contrived and somehow silly, the code doesn't do anything useful. It was for demonstration purposes. Let's see an example of an annotation that's used very often and which is extremely helpful: <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Override.html" target="_blank" class="link-underline link-underline-opacity-0"> @Override </a>. </p> <p> This annotation provides us with great benefit during compile-time by "forcing" us to properly implement an <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Object.html#equals(java.lang.Object)" target="_blank" class="link-underline link-underline-opacity-0"> equals </a> method in our class. </p> <p> Consider the common error made when overriding, shown in the next code snippet: </p> <pre><code class="language-java"> class Processor { public boolean equals(Processor obj) { // return true or false ... omitted for brevity } } </code></pre> <p> In this code there's one subtle mistake: the argument received in the <code>equals</code> method is of type <code>Processor</code>, but it should be of type <code>Object</code> as per the specs. However, we may not notice it. And the compiler can't help us: it's a completely valid java code; in fact this code creates an accidental <a href="https://docs.oracle.com/javase/tutorial/java/javaOO/methods.html" target="_blank"> overload </a>. </p> <p> <code>@Override</code> to the rescue! If we annotate the method with <code>@Override</code>, now the compiler knows we're intending to override the <code>Object</code>'s <code>equals</code> method and reports an error at compile time (Something like <em>"Method does not override method from its superclass"</em>). </p> <p> This would be the fixed version of the previous code: </p> <pre><code class="language-java"> @Override public boolean equals(Object obj) { // code omitted for brevity } </code></pre> <p> It's worth mentioning that we're not limited to the <code>equals</code> method. We can use this annotation with any method we intend to override from some of the class ancestors. </p> <h2 id="why-do-we-need-interfaces">Do we need annotation interfaces?</h2> <p> Technically speaking, we may not strictly need them to write our day to day software, but it's really difficult for me to imagine any modern Java program that doesn't use some form of annotation. They enhance our code in ways that makes our lives (as developers) much easier than if we had to do the same work programmatically. </p> <p> Annotations are also used to provide metadata at runtime. For example, the Jakarta Persistence API ( <a href="https://en.wikipedia.org/wiki/Jakarta_Persistence" target="_blank"> JPA </a>) uses several annotations from the package <code>jakarta.persistence</code> to work internally and provide all the features it provides. So, it's not only small enhancements we get in our code; we're talking at this point of entire frameworks relying on annotations to function properly. This is something I don't see going away any time soon. </p> <h2 id="final-thoughts">Final thoughts</h2> <p> There's a bunch of articles, official documentation, and books out there that we can read to get more knowledge about annotations. Hopefully, this is a good start for you to increase your knowledge a bit more about the Java platform and sparkle your interest in reading more about interface annotations and other use cases and details not covered in this article. </p> <hr/> <p> <sup>1</sup>: While the structure and most of the "rules" are the same, there are actually some subtle differences. For example, the return type of a method declared in the body of annotation interface must be one of: a primitive type, <code>String</code>, <code>Class</code> or an invocation of <code>Class</code>, an enum class type, an annotation interface type, or an array type whose component type is one of the previously mentioned types. If such return type is different, a compile-time error occurs. </p> asiel@lealceldeiro.com(Asiel Leal Celdeiro) https://lealceldeiro.com/articles/2024/java-interfaces.html Wed, 17 Jan 2024 00:00:00 +0000 articles/2024/java-interfaces.html <h2 id="what-s-a-java-interface">What's a Java interface?</h2> <p> If you ask someone who's not a programmer, or software engineer, or the like, "what's an interface?", most probably you'll get answers around "it's a boundary where two entities interact", "it's some sort of connection between two things through which they interact with each other", or "it's the means through which two unrelated elements interact with each other". </p> <p>Then, what's a Java interface?</p> <p> Interfaces in Java define behaviors. These behaviors are expressed as a <a href="https://docs.oracle.com/javase/tutorial/java/concepts/interface.html" target="_blank">group of methods</a> in the body of the interface. </p> <p> Then, some <a href="https://lealceldeiro.com/articles/2024/java-oop-classes-and-objects.html" target="_blank">class</a> can implement the interface methods as it sees fit, that's it, it defines how the behaviors specified in the interface are actually implemented. This class would be the first "entity" from our previous wider definition of interface. </p> <p> The second "entity", the one that would interact with the class implementation through the interface, would be the caller: the one that <em>calls</em> the methods. </p> <p> In summary we could say: the interface defines what behaviors/methods it provides to callers, and that must be implemented by any concrete class. It establishes a well-defined <a href="https://en.wikipedia.org/wiki/API" target="_blank">API</a> contract between two parties: one party that provides the implementation and another party that will consume it. </p> <p> If we were to create a simulation of a restaurant to illustrate the usage of an interface. We could have three elements: </p> <ul> <li>A customer</li> <li>A waiter</li> <li>The interface, through which the customer asks the waiter to bring some food</li> </ul> <p> We could call these three elements like this, respectively: </p> <ul> <li><code>Customer</code> (class)</li> <li><code>Waiter</code> (another class)</li> <li><code>OrderProcessor</code> (the interface)</li> </ul> <h2 id="interface-declaration-in-java">How does an interface declaration look like in Java?</h2> <p>Let's look at an example, by following our previous analogy of the restaurant:</p> <pre><code class="language-java"> // interface declaration interface OrderProcessor { // here we declare only the method (behavior) - but not the actual implementation public void bringFood(String dishName); } // a class that implements the interface class Waiter implements OrderProcessor { // the actual logic of the method (body of the method) is defined here public void bringFood(String dishName) { System.out.println("Brought " + dishName + " to customer"); } } // another class that can ask for food class Customer { private String favoriteDish = "Fish and Vegetables"; void askForFood(OrderProcessor orderProcessor) { // the customer interacts with the interface OrderProcessor orderProcessor.bringFood(favoriteDish); } } </code></pre> <p> This interface is called <code>OrderProcessor</code> and it defines the "bring food" behavior, which is declared as a method named: <code>bringFood</code>. </p> <p>This is a very simple example; let's dive deeper into the intricacies of interfaces in Java.</p> <h2 id="diving-deeper-into-java-interfaces">Diving deeper into Java interfaces</h2> <h3 id="declaring-an-interface">Declaring an interface</h3> <p>There are two types of interface declarations:</p> <ul> <li><em>Normal interface declarations</em></li> <li><em>Annotation interface declarations</em></li> </ul> <p> In this article only the normal interface declaration is covered. Annotation interface declaration will be covered in a separate article. </p> <p>Let's see the structure of an interface declaration:</p> <pre><code class="language-java"> {InterfaceModifier} interface TypeIdentifier [TypeParameters] [InterfaceExtends] [InterfacePermits] InterfaceBody </code></pre> <p>Where</p> <ul> <li> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-InterfaceModifier" target="_blank" class="link-underline link-underline-opacity-0"> <code>{InterfaceModifier}</code> </a> is one of: <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-Annotation" target="_blank" class="link-underline link-underline-opacity-0"> <code>Annotation</code> </a>, <code>public</code>, <code>protected</code>, <code>private</code>, <code>abstract</code>, <code>static</code>, <code>sealed</code>, <code>non-sealed</code>, <code>strictfp</code>. </li> <li><code>interface</code> is the Java keyword used to specify we're declaring an interface.</li> <li> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-3.html#jls-TypeIdentifier" target="_blank" class="link-underline link-underline-opacity-0"> <code>TypeIdentifier</code> </a> is the name we want to give the interface. In our previous example we used <code>OrderProcessor</code>. </li> <li> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-TypeParameters" target="_blank" class="link-underline link-underline-opacity-0"> <code>[TypeParameters]</code> </a> is a collection of <em>types</em> we can define within angle brackets (<code><></code>). For instance,<code><T></code>. See <a href="https://docs.oracle.com/javase/tutorial/extra/generics/index.html" target="_blank"> generics </a> and <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.1.2" target="_blank"> §8.1.1 </a> for more info about this. </li> <li> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-InterfaceExtends" target="_blank" class="link-underline link-underline-opacity-0"> <code>[InterfaceExtends]</code> </a> is the portion of the interface declaration where we can specify, after the keyword <code>extends</code>, the interface (if any) from which our interface is a direct subinterface. For instance, <code>extends Processor</code>. </li> <li> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-InterfacePermits" target="_blank" class="link-underline link-underline-opacity-0"> <code>[InterfacePermits]</code> </a> is used when the <code>sealed</code> modifier is specified, and it indicates, after the keyword <code>permits</code>, the other classes or interfaces (if any) that are allowed to implement/extend our interface. For example, <code>permits OrderProcessor, SuperWaiter</code>. </li> <li> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-InterfaceBody" target="_blank" class="link-underline link-underline-opacity-0"> <code>InterfaceBody</code> </a> is the <code>body</code> of our interface, including the curly braces (<code>{}</code>). See next section. </li> </ul> <p> It's important to note that unlike a class, an interface cannot be declared <code>final</code>. However, an interface may be declared <code>sealed</code> ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-9.1.1.4" target="_blank"> §9.1.1.4 </a>) to limit its subclasses and subinterfaces. </p> <h4 id="interface-body">Interface body</h4> <p> The structure of an interface body ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-InterfaceMemberDeclaration" target="_blank" class="link-underline link-underline-opacity-0"> <code>{InterfaceMemberDeclaration}</code> </a>) is as follows: </p> <pre><code class="language-java"> { ConstantDeclaration InterfaceMethodDeclaration ClassDeclaration InterfaceDeclaration } </code></pre> <p>Let's see what each of these elements are, and some examples of how they're used.</p> <h5 id="interface-constants">Constants</h5> <p> Constants ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-ConstantDeclaration" target="_blank" class="link-underline link-underline-opacity-0"> <code>ConstantDeclaration</code> </a>) can be referred to as interface attributes, properties, fields. They are similar to class fields, except they can NOT be modified —they're final—, and their declaration is as follows: </p> <pre><code class="language-java"> {ConstantModifier} UnannType VariableDeclaratorList; </code></pre> <p>In this case</p> <ul> <li> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-ConstantModifier" target="_blank" class="link-underline link-underline-opacity-0"> <code>ConstantModifier</code> </a> can be any of the previously mentioned <code>Annotation</code>, <code>public</code>, <code>static</code>, and/or <code>final</code>. </li> <li> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-UnannType" target="_blank" class="link-underline link-underline-opacity-0"> <code>UnannType</code> </a>, in short, refers to all the types we can use to declare what type the field is. For example, <code>Integer</code>. </li> <li> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-VariableDeclaratorList" target="_blank" class="link-underline link-underline-opacity-0"> <code>VariableDeclaratorList</code> </a>, simply put, is the actual name of the field (variable) and, optionally, and initializer. </li> </ul> <p> Let's see an example of a constant in our <code>OrderProcessor</code> interface. </p> <pre><code class="language-java"> interface OrderProcessor { public int MAX_ORDERS_NUMBER = 1000; // ... rest of the code omitted for brevity } </code></pre> <p> Here, we declared a constant <code>MAX_ORDERS_NUMBER</code> of type <code>int</code> with a value of <code>1000</code>. It is <code>public</code> (default in interfaces), so it's publicly accessible by anyone with access to the interface. </p> <h5 id="interface-method-declarations">Method declarations</h5> <p> Method declarations ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-InterfaceMethodDeclaration" target="_blank" class="link-underline link-underline-opacity-0"> <code>InterfaceMethodDeclaration</code> </a>) are the declarations of the methods defined in the interface. They are the methods that must be implemented by any class that implements the interface, unless the interface itself provides a default implementation. </p> <p> Default method implementations is a feature added in <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/language/enhancements.html#javase8" target="_blank"> Java 8 </a> that allows us to define the method body (its actual implementation) in the interface itself, as opposite to abstract methods, which require a concrete class to implement them. </p> <p> More formally, a <em>default method</em> is an instance method declared in an interface with the <code>default</code> modifier. Its body is always represented by a block, which provides a default implementation for any class that implements the interface without overriding the method. These methods are distinct from concrete methods, which are declared in classes, and from <code>private</code> interface methods, which are neither inherited nor overridden ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-9.4" target="_blank"> §9.4 </a>). </p> <p> Let's see now how to declare these methods in our <code>OrderProcessor</code> interface. </p> <pre><code class="language-java"> interface OrderProcessor { public int MAX_ORDERS_NUMBER = 1000; // abstract method -- must be implemented by the concrete class public void bringFood(String dishName); // also, an abstract method -- must be implemented by the concrete class public abstract void bringWater(); // any class implementing the interface will inherit this // default method implementation, unless overridden default String getType() { return "Waiter"; } // only available to be called within the interface itself private int getMaxOrders() { return MAX_ORDERS_NUMBER; } } </code></pre> <h5 id="interface-nested-class-declaration">Class declaration</h5> <p> Nested (or inner) class declarations ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-ClassDeclaration" target="_blank" class="link-underline link-underline-opacity-0"> <code>ClassDeclaration</code> </a>) were covered in a previous post ( <a href="https://lealceldeiro.com/articles/2024/java-oop-classes-and-objects.html#nested-classes" target="_blank"> Java classes and objects </a>). Let's quickly review an example of how it would look like in the body of an interface: </p> <pre><code class="language-java"> interface OrderProcessor { // nested class declaration class BillCalculator { } // ... rest of the code omitted for brevity } </code></pre> <h5 id="interface-inner-interface-declaration">Interface Declaration</h5> <p> Nested interface declarations ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-InterfaceDeclaration" target="_blank" class="link-underline link-underline-opacity-0"> <code>InterfaceDeclaration</code> </a>) were also covered in <a href="https://lealceldeiro.com/articles/2024/java-oop-classes-and-objects.html#nested-interfaces" target="_blank"> that post </a>. Let's see how to use it in our example. </p> <pre><code class="language-java"> interface OrderProcessor { interface Calculator { } // ... rest of the code omitted for brevity } </code></pre> <h3 id="implementing-an-interface">Implementing an interface</h3> <p> An interface is not of much use without a concrete class that implements its methods. So, let's get into how a class can implement the methods defined in the body of an interface. </p> <p> A class can be declared to <em>directly implement</em> one or more interfaces ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html" target="_blank">§9</a>, <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.1.5" target="_blank"> §8.1.5 </a>). This means that any instance of that class implements all the <code>abstract</code> methods specified by the interface. </p> <p> A class necessarily implements all the interfaces that its direct superclasses and direct superinterfaces do. This multiple interface inheritance allows objects to support multiple common behaviors without sharing a superclass (<a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html" target="_blank">§9</a>). </p> <p>Let's review again our previous example.</p> <pre><code class="language-java"> interface OrderProcessor { public void bringFood(String dishName); } class Waiter implements OrderProcessor { public void bringFood(String dishName) { System.out.println("Brought " + dishName + " to customer"); } } </code></pre> <p> Here, we specify after the keyword <code>implements</code> all the interfaces that the class implements. Notice that it's mandatory for the <code>Waiter</code> class to implement the method <code>bringFood</code>, otherwise the code won't compile. </p> <p> Let's see how the <code>Waiter</code> class can implement another interface: <code>Serializable</code>, which belongs to the <code>java.io</code> package. </p> <pre><code class="language-java"> class Waiter implements OrderProcessor, Serializable { public void bringFood(String dishName) { System.out.println("Brought " + dishName + " to customer"); } } </code></pre> <p> As you notice, we only need to add the new interface being implemented after a comma (<code>,</code>). This way we can implement all the interfaces we want. </p> <h3 id="extending-an-interface">Extending an interface</h3> <p> Sometimes there are interfaces that do not provide all the method declarations we need. In such cases, sometimes we need to create an interface that "inherits" that other interface method declarations, and, on top of that, add our own. This way any class implementing the new interface will inherit all the methods. This is a <a href="https://dzone.com/articles/introduction-spring-data-jpa-inheritance-rest-app" target="_blank"> common pattern used </a> when implementing our own <a href="https://spring.io/projects/spring-data-jpa/" target="_blank">Spring Data JPA</a> Repositories. </p> <p> An interface may be declared to be a <em>direct extension</em> of one or more other interfaces, meaning that it inherits all the member classes and interfaces, instance methods, and <code>static</code> fields of the interfaces it extends, except for any members that it may override or hide ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html" target="_blank">§9</a>). </p> <p>Let's see in our example how would such extension look like.</p> <pre><code class="language-java"> interface Processor<T> { // 1 public void process(T element); // 2 } interface OrderProcessor extends Processor<String> { // 3 public void bringFood(String dishName); public default void process(String dishName) { // 4 bringFood(dishName); } } </code></pre> <p> There are several things going on in this example, so let's review it, point by point from the previous commented lines: </p> <ol> <li> <code>Processor</code> is declared as a generic interface that accepts a type <code>T</code> (this is the type of the elements the interface will work with). See <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-9.1.2" target="_blank"> §9.1.2 </a> for more information about this. </li> <li> <code>Processor</code> declares an abstract method called <code>process</code>, which takes an argument of type <code>T</code>. </li> <li> <code>OrderProcessor</code> extends <code>Processor</code> and it specifies that the elements it will work with are of type <code>String</code>. </li> <li> <code>OrderProcessor</code> provides a default implementation for the <code>process</code> method, inherited from <code>Processor</code>. The default implementation is actually just a call to the abstract method <code>bringFood</code> and it will be inherited by any concrete class. </li> </ol> <p>This example shows how powerful our implementations can be by combining different Java features.</p> <h3 id="evolving-interfaces">Evolving interfaces</h3> <p> When an interface is defined and made available to client code (let it be our own code, library users, or third party vendors who rely on our interfaces definitions), it's extremely important to be careful with how we evolve it so we don't break existing code that use the current API contract defined by the interface. </p> <p> While this is a topic for another whole article. There are some important points we should touch upon here. The following points are an extract from <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-13.html#jls-13.5" target="_blank"> §13.5 </a>. </p> <ul> <li> If an interface that is declared <code>public</code> is changed to not be declared <code>public</code>, then an <code>IllegalAccessError</code> is thrown if a pre-existing binary is linked that needs but no longer has access to the interface type, so such a change is not recommended for widely distributed interfaces. </li> <li> If an interface that was freely extensible ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-9.1.1.4" target="_blank"> §9.1.1.4 </a>) is changed to be declared <code>sealed</code>, then an <code>IncompatibleClassChangeError</code> is thrown if a binary of a pre-existing subclass or subinterface of this interface is loaded and is not a permitted direct subclass or subinterface of this interface ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-9.1.4" target="_blank"> §9.1.4 </a>); such a change is also not recommended for widely distributed classes. </li> <li> Adding an interface to the set of permitted direct subinterfaces of a <code>sealed</code> interface will not break compatibility with pre-existing binaries. However, it may cause the execution of an exhaustive <code>switch</code> ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-14.html#jls-14.11.1" target="_blank"> §14.11.1 </a>) to fail with an error (a <code>MatchException</code> may be thrown) if the <code>switch</code> encounters an instance of the new permitted direct subinterface that was not known at compile time ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-14.html#jls-14.11.3" target="_blank">§14.11.3</a>, <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-15.html#jls-15.28.2" target="_blank">§15.28.2</a>). </li> <li> If a class or interface is removed from the set of permitted direct subclasses or subinterfaces of a <code>sealed</code> interface, then an <code>IncompatibleClassChangeError</code> is thrown if the pre-existing binary of the removed class or interface is loaded. </li> <li> Changing an interface that was declared <code>sealed</code> to be declared <code>non-sealed</code> does not break compatibility with pre-existing binaries. However, a <code>non-sealed</code> interface <em>X</em> must have a <code>sealed</code> direct superinterface. Deleting the <code>non-sealed</code> modifier would prevent <em>X</em> from being recompiled, as every interface with a <code>sealed</code> direct superinterface must be <code>sealed</code> or <code>non-sealed</code>. </li> <li>Deleting a member from an interface may cause linkage errors in pre-existing binaries.</li> </ul> <h3 id="interface-examples">Examples</h3> <p>Let's see some more examples.</p> <h4 id="example1">A public generic interface with two constants, one private method and one public method</h4> <pre><code class="language-java"> public interface Processor<T> { int MAX_PROCESSES = 5; boolean LANGUAGE_AGNOSTIC = true; public void process(T element); private boolean isValid(T e) { return e != null; } } </code></pre> <h4 id="example2"> A public interface with one static inner class and one static inner interface; both of them have package-private visibility </h4> <pre><code class="language-java"> public interface OrderProcessor { class Sender { // <-- the 'static' keyword is default here before the keyword 'class' } static interface Calculator { } } </code></pre> <h4 id="example3">A package-private interface with one public static nested interface</h4> <pre><code class="language-java"> interface OrderProcessor { public static interface Calculator { } } </code></pre> <h4 id="example5"> A sealed interface that permits another sealed interface to extend it, and a final class that implements the intermediate interface </h4> <pre><code class="language-java"> sealed interface Processor<T> permits OrderProcessor { void process(T element); } sealed interface OrderProcessor extends Processor<String> { void process(String order); } final class Waiter implements OrderProcessor { public void process(String order) { System.out.println("Brought " + order + " to customer"); } } </code></pre> <h4 id="example6"> A sealed interface that permits another non-sealed interface to extend it, and a NON-final class that implements the intermediate interface </h4> <pre><code class="language-java"> sealed interface Processor<T> permits OrderProcessor { void process(T element); } non-sealed interface OrderProcessor extends Processor<String> { void process(String order); } class Waiter implements OrderProcessor { public void process(String order) { System.out.println("Brought " + order + " to customer"); } } </code></pre> <h4 id="example7"> A sealed interface that permits a final class to implement it </h4> <pre><code class="language-java"> sealed interface OrderProcessor permits Waiter { void process(String order); } final class Waiter implements OrderProcessor { public void process(String order) { System.out.println("Brought " + order + " to customer"); } } </code></pre> <h3 id="why-do-we-need-interfaces">Why do we need interfaces?</h3> <p> While interfaces are not a mandatory component of the software we implement, it's true our programs can use interfaces to provide a common supertype for otherwise unrelated classes, and to make it unnecessary for related classes to share a common <code>abstract</code> superclass ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html" target="_blank">§9</a>). </p> <p> Many software patterns have been put into practice taking into account the concept of interfaces. These patterns solve well-known problems with a defined context and solution. Just to mention a few, we could point out <a href="https://en.wikipedia.org/wiki/SOLID" target="_blank">SOLID</a>, and many of the patterns presented by <a href="https://en.wikipedia.org/wiki/Design_Patterns" target="_blank">GoF</a>; thus they bring flexibility, robustness, re-usability and a lot more benefits to our well-designed software solutions. </p> <p> Nowadays, when systems are more complex, and we need to model more complex scenarios as well, interfaces play a vital role in promoting a loose coupling between the elements of our software. They're also a very powerful element of Java: they allow a class to inherit behaviors from multiple supertypes (so we can overcome the "limitation" of not having <a href="https://medium.com/edureka/multiple-inheritance-in-java-a996c26143ac" target="_blank"> multiple inheritance in Java </a>), they play a pivotal role in <a href="https://docs.oracle.com/javase/tutorial/java/IandI/polymorphism.html" target="_blank"> polymorphism </a>, they allow us to define clear boundaries and responsibilities for each software component and in most cases they make easier for us to implement automated test for the code we write. </p> <h2 id="final-thoughts">Final thoughts</h2> <p> There is so much material we could revise about Java interfaces that this single article wouldn't be enough to cover it all. I've presented here high level information as well as several of the implementation details about this topic which I hope, along with the linked documentation, is a good start for you to review and deepen your knowledge about Java. </p> asiel@lealceldeiro.com(Asiel Leal Celdeiro) https://lealceldeiro.com/articles/2024/java-oop-classes-and-objects.html Wed, 10 Jan 2024 00:00:00 +0000 articles/2024/java-oop-classes-and-objects.html <h2 id="what-are-java-classes">What are Java classes and objects?</h2> <p> To put it simple, a <strong>Java class</strong> is a "form of classification". It is a concept from <em>Object-Oriented Programming (OOP)</em> that allows us to "classify" (or group together) a type of <em>object(s)</em> —another concept from OOP— An <strong>object</strong> represents a specific instance of a class. With classes and objects we can represent real-world concepts and entities in our programs as well as their interactions. </p> <p> For instance, in a program called <em>ZooManager</em> we could have the following classes: <code>Animal</code>, <code>Cage</code>, <code>Food</code>, and <code>ZooKeeper</code>. Likewise, the specific animal, cage, food and zookeeper <em>instances</em> that are present in the Zoo we're managing would be the objects instantiated during the execution of the program. In this case, examples of instances would be <code>teo</code> (a tiger), <code>cage1</code> (a cage), <code>meat</code> (food), and <code>john</code> (a zookeeper). </p> <h3 id="how-to-decide-which-classes-to-define">How do we decide which classes to define in our program?</h3> <p> Classes define common <em>properties</em> and <em>behaviors</em> for the objects they represent. For example, the <code>Animal</code> class would have the following properties: </p> <ul> <li><code>name</code></li> <li><code>energy</code></li> </ul> <p>and the following behaviors</p> <ul> <li> <code>move</code> (if an animal moves, it consumes energy, the <code>energy</code> property decreases) </li> <li> <code>eat</code> (if an animal eats, it recovers energy, the <code>energy</code> property increases) </li> </ul> <p> So, when we identify a collection of objects in our business domain that share the same properties and behaviors, we are usually in the presence of a class to be defined in our program. Sometimes it can be obvious, like knowing we'll need a class called <code>Animal</code> in our ZooManager program, but sometimes it's more difficult to identify when we would benefit from the definition of a class. As we gain experience throughout the years, as developers/software engineers, it becomes easier to identify each case. </p> <h3 id="syntax">Syntax</h3> <p> The simplest form of a class definition in Java you could find is this (<code>Animal</code> could have been any other name we define): </p> <pre><code class="language-java"> class Animal { } </code></pre> <p> But that class isn't very useful, is it? So, let's see everything we have in our power to declare and define our own classes. </p> <h3 id="structure">Structure</h3> <p> Let's use the chapter about classes from the <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html" target="_blank"> Java Language Specification (JLS) for Java 21 </a> to understand the anatomy of a class in Java. Notice you may want to check the <a href="https://docs.oracle.com/javase/specs/" target="_blank">JLS specific to your Java version</a>. </p> <p>Formally, this is the structure of a Java class:</p> <pre><code class="language-java"> {ClassModifier} class TypeIdentifier [TypeParameters] [ClassExtends] [ClassImplements] [ClassPermits] ClassBody </code></pre> <p>Where</p> <ul> <li> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-ClassModifier" target="_blank" class="link-underline link-underline-opacity-0"> <code>{ClassModifier}</code> </a> is one of: <code>public</code>, <code>protected</code>, <code>private</code>, <a href="/articles/2024/abstrat-classes-in-java.html" target="_blank" class="link-underline link-underline-opacity-0"> <code>abstract</code> </a>, <code>static</code>, <code>final</code>, <a href="/articles/2024/sealed-classes-in-java.html#sealed-keyword" target="_blank" class="link-underline link-underline-opacity-0"> <code>sealed</code> </a>, <code>non-sealed</code>, <code>strictfp</code>. </li> <li><code>class</code> is the Java keyword used to specify we're declaring a class.</li> <li> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-3.html#jls-TypeIdentifier" target="_blank" class="link-underline link-underline-opacity-0"> <code>TypeIdentifier</code> </a> is the name we want to give the class. In our previous example we used <code>Animal</code>. </li> <li> <!--https://en.wikipedia.org/wiki/List_of_typographical_symbols_and_punctuation_marks--> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-TypeParameters" target="_blank" class="link-underline link-underline-opacity-0"> <code>[TypeParameters]</code> </a> is a collection of <em>types</em> we can define within angle brackets (<code><></code>). For instance, <code><T></code>. See <a href="https://docs.oracle.com/javase/tutorial/extra/generics/index.html" target="_blank"><em>generics</em></a> and <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.1.2" target="_blank">JLS</a> for more info about this. </li> <li> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-ClassExtends" target="_blank" class="link-underline link-underline-opacity-0"> <code>[ClassExtends]</code> </a> is the portion of the class declaration where we can specify, after the keyword <code>extends</code>, the class (if any) from which our class is a direct child (descendant, inheritor). For instance, <code>extends LivingBeing</code>. </li> <li> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-ClassImplements" target="_blank" class="link-underline link-underline-opacity-0"> <code>[ClassImplements]</code> </a> is the portion of the class declaration where we can list, after the keyword <code>implements</code>, the <a href="https://lealceldeiro.com/articles/2024/java-interfaces.html" target="_blank"> interfaces </a> (if any) whose behavior our class implements. For instance, <code>implements MovingBeing, Eater</code>. </li> <li> <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-ClassPermits" target="_blank" class="link-underline link-underline-opacity-0"> <code>[ClassPermits]</code> </a> is used when the <a href="/articles/2024/sealed-classes-in-java.html#sealed-keyword" target="_blank" class="link-underline link-underline-opacity-0"> <code>sealed</code> </a> modifier is specified, and it indicates, after the keyword <a href="/articles/2024/sealed-classes-in-java.html#permits-keyword" target="_blank" class="link-underline link-underline-opacity-0"> <code>permits</code> </a>, the other classes (if any) that are allowed to extend our class. For example, <code>permits Tiger, Ostrich, Bear</code>. </li> <li> and, <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-ClassBody" target="_blank" class="link-underline link-underline-opacity-0"> <code>ClassBody</code> </a>, <!--https://www.compart.com/en/unicode/html--> is the <em>body</em> of our class, including the curly braces ({}). See next section. </li> </ul> <h4 id="class-body">Class body</h4> <p> In short, this is the structure of the class body ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-ClassBodyDeclaration" target="_blank" class="link-underline link-underline-opacity-0"> <code>{ClassBodyDeclaration}</code> </a>): </p> <pre><code class="language-java"> { ClassMemberDeclaration InstanceInitializer StaticInitializer ConstructorDeclaration } </code></pre> <p> Let's see what these elements are, along with some examples. </p> <h5 id="members">Members</h5> <p> With <em>members</em> ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-ClassMemberDeclaration" target="_blank" class="link-underline link-underline-opacity-0"> <code>ClassMemberDeclaration</code> </a> ), we refer to <em>fields</em> ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-FieldDeclaration" target="_blank" class="link-underline link-underline-opacity-0"> <code>FieldDeclaration</code> </a> ), <em>methods</em> ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-MethodDeclaration" target="_blank" class="link-underline link-underline-opacity-0"> <code>MethodDeclaration</code> </a> ), <em>nested classes</em> ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-ClassDeclaration" target="_blank" class="link-underline link-underline-opacity-0"> <code>ClassDeclaration</code> </a> ), and <em>nested interfaces</em> ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-9.html#jls-InterfaceDeclaration" target="_blank" class="link-underline link-underline-opacity-0"> <code>InterfaceDeclaration</code> </a> ). The first two are the respective <em>properties</em> and <em>behaviors</em> that we were referring to initially. The other two are covered in next sections, along with <code>InstanceInitializer</code> and <code>StaticInitializer</code>. </p> <p>Let's see fields and methods.</p> <h6 id="fields">Fields</h6> <p> Fields are properties, attributes that characterize our classes, they hold the state of the objects created from our classes and are useful for storing the objects information during runtime. </p> <p> We saw already some examples of properties for our mentioned <code>Animal</code> class. Now, let's see how we can actually write that in our code. Let's enhance our <code>Animal</code> class with some fields: </p> <pre><code class="language-java"> class Animal { String name; int energy; } </code></pre> <h6 id="methods">Methods</h6> <p> Methods define the behavior of the objects, they specify what "actions" the objects can do during the execution of our program, they define the <a href="https://en.wikipedia.org/wiki/API" target="_blank"> API </a> through which we (technically speaking, other objects) can interact with them. They can do two things: return information about the object, and/or modify it, that's it, modify the internal state of the object. </p> <p> Let's see how we can define the actions our <code>Animal</code> objects can do: </p> <pre><code class="language-java"> class Animal { String name; int energy; void move() { energy--; System.out.println(name + " moved"); } void eat() { energy++; System.out.println(name + " ate"); } } </code></pre> <p> In this example, the method <code>move</code> decreases the <em>energy</em> value and prints the name of the animal that moved (i.e.: <code>teo moved</code>). </p> <p> The method <code>eat</code> does the opposite: it increases the <em>energy</em> value, and also prints the name of the animal that ate (i.e.: <code>teo ate</code>). </p> <h5 id="constructors">Constructors</h5> <p>So far, we've talked a lot about Java classes, but not so much about the objects.</p> <p> Just to make sure we understand the concept of <em>object</em>, if we were to make an analogy, we could say that <em>Woman</em> is a class, while <em>Ana</em> is an object. Similarly, <em>Man</em> is a class, and <em>John</em> is an object. </p> <p> Now, let's see how we can create objects in our programs. Java provides us with something called <em>constructors</em> ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-ConstructorDeclaration" target="_blank" class="link-underline link-underline-opacity-0"> <code>ConstructorDeclaration</code> </a> ). They are a "special" piece of code inside the body of our class that allow us to <em>instantiate</em>, <em>create</em> objects from a class definition. </p> <p> This is the structure of the constructor. Look closely; it looks similar to a method, but it lacks a return type: </p> <pre><code class="language-java"> {ConstructorModifier} ConstructorDeclarator [Throws] ConstructorBody </code></pre> <p> But, it can be better understood with an example, so let's see it in action in our <code>Animal</code> class. </p> <pre><code class="language-java"> class Animal { String name; int energy; Animal(String name) { // <-- Constructor added this.name = name; energy = 100; } // rest of the code omitted for brevity... } </code></pre> <p> Here we've created a constructor that accepts a <code>name</code> argument and assigns it to the <code>name</code> field. It also initializes the <code>energy</code> field with a value of <code>100</code>. </p> <blockquote class="text-body-secondary"> Actually, there are other ways to create objects, but, to keep it simple, they're not covered here. If you feel curious about it, you can read more about <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Class.html#forName(java.lang.String)" target="_blank" class="link-underline link-underline-opacity-0"> <code>Class.forName(String className)</code> </a>, <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Object.html#clone()" target="_blank" class="link-underline link-underline-opacity-0"> <code>Object.clone()</code> </a>, and <a href="https://docs.oracle.com/javase/tutorial/jndi/objects/serial.html" target="_blank"> <em>Deserialization</em> </a>. </blockquote> <p> Up to here, we've defined the means to create an object of type <code>Animal</code>, but, how do we actually instantiate one? </p> <p> Simple, we use the <a href="https://docs.oracle.com/javase/tutorial/java/javaOO/objectcreation.html" target="_blank" class="link-underline link-underline-opacity-0"> <code>new</code> </a> keyword. </p> <pre><code class="language-java"> Animal teo = new Animal("Teo"); </code></pre> <h5 id="nested-classes">Nested classes</h5> <p> We've mentioned earlier that we can have <a href="https://docs.oracle.com/javase/tutorial/java/javaOO/nested.html" target="_blank"> nested classes </a> as a members of another class. But how does that actually look like? Well, it's quite simple once we have understood fields and methods because their declaration follows the same principle: it's a code structure that "belongs" to the class where they're declared. More, formally: a <em>member class</em> is a class whose declaration is <em>directly enclosed</em> in the body of another class or interface declaration ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.5" target="_blank"> JLS 8.5 </a>). Let's see an example. </p> <p> Let's suppose we want to represent each part of the body of an animal with a class. And then each animal would be formed by its parts —granted, this is a contrived example, only for demonstration purposes— </p> <p> At this point, we have two options:</p> <ol> <li> Create two independent classes, each in its own <code>.java</code> file (<code>Animal.java</code> and <code>BodyPart.java</code>) </li> <li> Create one top level class (<code>Animal</code>), and one inner class (<code>BodyPart</code>), both in one <code>.java</code> file called <code>Animal.java</code> </li> </ol> <p> How do we decide which option is better? Obviously "better" always depends on your specific use case, but for this example, let's say a <code>BodyPart</code> doesn't make any sense without an <code>Animal</code>, so it's better to model the solution as if it's a member of <code>Animal</code>. In this case we declare another class "inside" <code>Animal</code>, with all the same components we've discussed so far. </p> <pre><code class="language-java"> class Animal { class BodyPart { // <-- inner class added String partName; double weight; } /** * Holds the information for each body part of this animal. */ Collection<BodyPart> bodyParts; // rest of the code omitted for brevity... } </code></pre> <h5 id="nested-interfaces">Nested interfaces</h5> <p> It's difficult to explain what a <em>nested interface is</em> without knowing what's a Java <a href="https://lealceldeiro.com/articles/2024/java-interfaces.html" target="_blank"> interface </a>. To keep it simple, and focus on classes, which is the topic of the article, I'll oversimplify it: it's basically a group of related methods with empty bodies, and its declaration is quite similar to that of a class. For example, this is an interface called <code>MovingBeing</code>: </p> <pre><code class="language-java"> interface MovingBeing { void move(); } </code></pre> <p> Now, if we were to declare this interface as a member of the <code>Animal</code> class, we just need to follow the same logic we used to declare the inner class <code>BodyPart</code>: </p> <pre><code class="language-java"> class Animal { interface MovingBeing { // <-- inner interface added, not very useful now void move(); } // rest of the code omitted for brevity... } </code></pre> <p> More, formally: a <em>member interface</em> is an interface whose declaration is <em>directly enclosed</em> in the body of another class or interface declaration ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.5" target="_blank"> JLS 8.5 </a>). </p> <h5 id="instance-and-static-initializer">Instance and static initializer</h5> <p> There are two elements of the body of the class we haven't covered yet: instance initializers ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-InstanceInitializer" target="_blank" class="link-underline link-underline-opacity-0"> <code>InstanceInitializer</code> </a> ) and static initializers ( <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-StaticInitializer" target="_blank" class="link-underline link-underline-opacity-0"> <code>StaticInitializer</code> </a> ). </p> <p> They both are a <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-14.html#jls-Block" target="_blank">block</a> of code where some <em>initialization</em> happens. The only difference between them is that the instance initializer is tied to the life-cycle of the object being created; hence, the code block is executed once for each object created. The static initializer, on the other hand, is executed only when the class is loaded (usually only once during the program execution). This is more related to the concept of <a href="https://docs.oracle.com/javase/tutorial/java/javaOO/classvars.html" target="_blank" class="link-underline link-underline-opacity-0"> <code>static</code> </a> members (see <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-8.html#jls-8.3.1.1" target="_blank">JLS</a>). </p> <p> Let's see them in an example. </p> <h6>Instance initializers</h6> <p> Let's suppose we want to move the initialization of the field <code>energy</code> out of the constructor. We can do it by placing the expression <code>energy = 100;</code> inside an instance initializer: </p> <pre><code class="language-java"> class Animal { String name; int energy; { energy = 100; // <-- initialization moved to this instance initializer } Animal(String name) { this.name = name; } // rest of the code omitted for brevity... } </code></pre> <h6>Static initializers</h6> <p> Now, let's suppose that we want to have a field inside the <code>Animal</code> class called <code>perceivedTemperature</code>, which indicates the environment temperature perceived by the animals. In this case we don't want to have a separate value for each animal, because we can say this temperature is the same for every animal —again, this is a contrived example, for demonstration purposes— </p> <p> To store such field we should not do it with an instance field, but with a static one. This way, when the field is modified, we get the same value, regardless of the <code>Animal</code> instance the value is being accessed from. It would look like this: </p> <pre><code class="language-java"> class Animal { static double perceivedTemperature; // rest of the code omitted for brevity... } </code></pre> <p> Now, we would like to initialize it in an instance initializer block, how do we do it? Simple: </p> <pre><code class="language-java"> class Animal { static double perceivedTemperature; static { perceivedTemperature = 32.4d; } // rest of the code omitted for brevity... } </code></pre> <h2>The <em>.java</em> file</h2> <p>Where do we write our classes? Inside <code>.java</code> files.</p> <p> Most of the time, each class is defined in its own <code>.java</code> file. Such class is called a <em>top level</em> class (type). </p> <p> But it's not mandatory to have only one top level type in a <code>.java</code> file. We can define several of them, as long as <em>at most one</em> of them is <code>public</code>. Put in another way: we can not declare more than one public top level type in the same <code>.java</code> file. </p> <h3>Putting it all together</h3> <p>Let's see some examples where we apply all the knowledge we've learned.</p> <h4>Examples</h4> <h5>A public class with two fields, two methods, and one constructor</h5> <p>We saw this one already, but for the sake of completeness, let's review it:</p> <pre><code class="language-java"> public class Animal { String name; int energy; Animal(String name) { this.name = name; energy = 100; } void move() { energy--; System.out.println(name + " moved"); } void eat() { energy++; System.out.println(name + " ate"); } } </code></pre> <h5> A public class with one protected static inner class, two fields, one instance initializer, and one static initializer </h5> <pre><code class="language-java"> public class Animal { protected static class BodyPart { } String name; static double perceivedTemperature; { name = "Leo"; } static { perceivedTemperature = 32.4d; } } </code></pre> <h5>A package-private class with one private static inner class, and one public static inner interface</h5> <blockquote> Side note: interfaces are <code>static</code> by default, but I'm putting it here for demonstration purposes only. </blockquote> <pre><code class="language-java"> class Animal { private static class BodyPart { String partName; } public static interface MovingBeing { void move(); } } </code></pre> <h5>A sealed class that permits another final class to extend it</h5> <pre><code class="language-java"> sealed class Animal permits Tiger { } final class Tiger extends Animal { } </code></pre> <h5>A sealed class that permits another non-sealed class to extend it</h5> <pre><code class="language-java"> sealed class Animal permits Tiger { } non-sealed class Tiger extends Animal { } </code></pre> <h2>Could we implement our programs entirely without classes?</h2> <p> Certainly. Technically speaking, we don't need to create our own classes to implement a business logic. But, by doing so, we can structure better our code and re-use it more effectively, we can achieve more robust and secure software and more adaptable to future changes. The enormous benefits of designing our code around OOP concepts such as classes and objects pay off immensely in the long term. </p> <h2>Final thoughts</h2> <p> There are much more details to learn about Java classes and objects; we barely scratched the surface here, but hopefully, the content and links I've shared are a good start for you to continue learning on your own and apply that knowledge in building high quality software. </p> asiel@lealceldeiro.com(Asiel Leal Celdeiro) https://lealceldeiro.com/articles/2024/the-java-development-kit.html Thu, 4 Jan 2024 00:00:00 +0000 articles/2024/the-java-development-kit.html <p> The Java Development Kit (JDK) is a development environment for building applications and components using the <a href="https://docs.oracle.com/en/java/index.html" target="_blank">Java</a> programming language. It includes tools useful for developing, testing, and monitoring such programs written in Java and running on the Java platform. </p> <p> The available versions of the JDK can be checked on the official <a href="https://docs.oracle.com/en/java/javase/index.html" target="_blank">oracle website</a>, where there's detailed information about each specific release, along with instruction for their installation, and their <a href="https://www.oracle.com/java/technologies/downloads/" target="_blank">download url</a>. Speaking of instructions for installation, there are some nice tutorials in <a href="https://dev.java/learn/getting-started/" target="_blank">dev.java</a> that walk us through each specific step we must follow from the very beginning to get our first program up and running. </p> <p> When we download the JDK archive, we can find inside configuration files, <em>C</em> header files, compiled Java modules, copyright and license files and additional libraries. </p> <h2 id="key-commands">Key commands</h2> <p>The JDK provides several commands to work with our Java programs. Some of them are:</p> <h5 id="javac"><code>javac</code></h5> <p>This command converts .java source files into .class bytecode files.</p> <p>Let's suppose we have the following Java class inside a file called <em>MyClass.java</em>:</p> <pre><code class="language-java"> public class MyClass { } </code></pre> <p> Now, if we run <code>javac MyClass.java</code>, in the command line (at the same level the .java file is located at ), we'll see that a file <em>MyClass.class</em> is created. </p> <h5 id="java"><code>java</code></h5> <p>This one is used to execute the Java program we write.</p> <p> Following along with the previous example, let's now add some code that prints "Hello world" in console and exits. First, let's modify the class to look like this: </p> <pre><code class="language-java"> public class MyClass { public static void main(String[] args) { System.out.println("Hello world"); } } </code></pre> <p>Now let's re-compile it to get the new changes into the bytecode file (<code>javac MyClass.java</code>).</p> <p> Now we're ready to run it. Let's execute <code>java MyClass.class</code> from the command line (notice we provided the compiled file as the argument —the .class file—). You should see "Hello world" printed in console. </p> <p> As a side note, starting with Java 11, Java applications can be run without going through the compilation step, as long as the program is written in a single file. So in the previous example, this would have worked as well: <code>java MyClass</code>. </p> <h5 id="jar"><code>jar</code></h5> <p>This one is used mainly to package files together.</p> <p> In our example, we could use it to create an archive called <em>MyProgram.jar</em>, that contains one class file, <em>MyClass.class</em>, and set <code>MyClass</code> as the entry point. Like this: </p> <pre><code class="language-shell"> jar --create --file MyProgram.jar --main-class MyClass MyClass.class </code></pre> <p> If you feel curious, you can run the program, as a jar file now, with <code>java -jar MyProgram.jar</code> and you should see the exact same "Hello world" printed in console. </p> <h5 id="javadoc"><code>javadoc</code></h5> <p> This command is used to generate the API documentation from Java source files as HTML pages. </p> <p>If we add a documentation comment to our previous <code>main</code> method like this:</p> <pre><code class="language-java"> public class MyClass { /** * Entry point for our application. * * @param args Program arguments. */ public static void main(String[] args) { System.out.println("Hello world"); } } </code></pre> <p> And now run <code>javadoc MyClass.java</code>, we can see all the HTML files created by the tool to include our documentation. </p> <p> All of these commands and more are documented in details in the official documentation website. You should definitely check it to get to know all the details about how to use them in you program. </p> <h2 id="what-about-the-jre">What about the JRE?</h2> <p> JRE stands for Java Runtime Environment. It is a subset of the JDK that is not distributed anymore ( <a href="https://www.oracle.com/java/technologies/javase/11-relnote-issues.html" target="_blank">starting with Java11 </a> ). It only contained the tools needed to <em>run</em> a Java application. </p> asiel@lealceldeiro.com(Asiel Leal Celdeiro)