Forem: Anshul Bansal

10 features of a perfect BRD (business requirement document)

Anshul Bansal — Mon, 15 May 2023 12:25:18 +0000

Overview

In this post, we'll explain a business requirement document (BRD) and the 10 most important features of a perfect one.

What is a business requirement document (BRD)?

A document that discusses the business requirement of a project is called BRD. A business requirement document (BRD) is a crucial tool that outlines the objectives, scope, and specific requirements of a project.
BRD helps to bring everyone to the table to understand the business requirements in detail and the outcome of it.

Important points to include:

1. Project Overview

The project overview section provides a high-level summary of the project, including its purpose, goals, and the problem it aims to solve. It sets the context for the document, ensuring that everyone understands the project's background and objectives. In short - Whys and Whats are usually specs out here.

2. Stakeholders

Stakeholders cover all the persons involved in the business and feature discussions of the project - business owners, project managers, developers, designers, and any other key individuals who will contribute to or be affected by the project. Clearly defining stakeholders ensures effective communication and collaboration throughout the project lifecycle.

3. Objective

State the clear and specific objective of the project. This section articulates the desired outcome or deliverable that the project intends to achieve. It serves as a guiding principle for decision-making and helps align the team toward a common goal.

4. Success Metrics

Define the metrics or criteria that will determine the success of the project. These can be quantitative or qualitative indicators that measure the project's performance against the objectives. Clearly defined success metrics enable effective evaluation and assessment of the project's outcomes.

5. Assumptions

A section to list down any assumptions to consider while working on the project. Assumptions help to set the context and manage expectations. By identifying and documenting assumptions, the project team can address potential risks and uncertainties upfront.

6. Business requirements

This section mentions all business requirements of this project. Each requirement should be actionable and measurable to facilitate effective implementation. Hence, these business requirements will translate into features that will further convert into epics/stories/tasks.

7. Open questions

While discussing the business requirement, if stakeholders come across questions that aren't answered or need further clarification. This section captures those open questions and serves as a reference for ongoing discussions and issue resolution.

8. Scope

A clear scope of the project sets the boundaries for the teams. This includes what is included in the project as well as what is excluded. Defining the scope helps manage expectations and ensures that the project remains focused and achievable within the given constraints.

9. Quality control

Describe the processes and procedures that will be employed to ensure the quality of the project deliverables. This includes answers to questions like How will this project be tested? How will the team ensure the business requirements are met?

10. Business constraints

Identify and document any constraints or limitations of the project, such as budget, deadlines, resources, etc. Understanding and considering these constraints helps manage expectations and ensures realistic planning and execution.

Conclusion

In this quick post, we've discussed the 10 key features that make a perfect business requirement document (BRD) that includes a comprehensive project overview, clearly defined objectives, success metrics, and stakeholder data, and addressing important aspects such as assumptions, open questions, scope, quality control, and business constraints.

A well-crafted BRD becomes a valuable guide for successful project execution. By investing time and effort into it, we set the stage for effective communication, collaboration, and project success.

Training Curriculum for Junior Programmers

Anshul Bansal — Thu, 27 May 2021 13:42:45 +0000

1. Overview

Many of us are self-taught programmers in software development. Therefore, we often require a curriculum to learn and master the art of programming.

Not only a curriculum helps to achieve the learning goal efficiently but, it promotes self-discipline too.

In this article, we'll discuss a Training Curriculum for Full Stack Java Programmers (Junior).

Such a curriculum is usually used in companies like TCS and Infosys to groom fresh talents joining as Trainee Engineers (or Freshers). It helps them to learn software development, improves efficiency, and makes them ready for future assignments.

My Programming Journey to Senior Programmer

Anshul Bansal ・ Oct 18 '20

#beginners #codenewbie #productivity #programming

2. Training Curriculum

This training curriculum is in two phases - Foundation and Advanced Phase.

Foundation Phase focuses on concept building through theory and quick hands-on.

Furthermore, the Advanced Phase lets the programmers create an end-to-end web application utilizing all the learnings of the Foundation Phase.

3. Foundation Phase

The foundation phase is about learning the Java programming language along with OOP concepts and advanced features like
Collections, Multi-Threading, Garbage Collection. Then, we should focus on learning Database, SQL, and WEB UI.

Afterward, the knowledge of a few build tools like Gradle, frameworks like JUnit, helper tools like GIT & and SDLC methodologies like Agile will also be required.

Here, I've put each step into a box to segregate them from others. Also, we don't have a particular order of the steps.

A trainee can self-decide his order, moving from more interesting/relevant topics to the less significant ones.

Also, don't forget to follow a code review checklist and best practices for delivering better code.

Code Review Checklist for Java Beginners

Anshul Bansal ・ Jan 5 '20

#java #beginners #productivity #codequality

Coding Best Practices for Java Apps

Anshul Bansal ・ Nov 16 '20

#java #codequality #productivity #beginners

4. Advanced Phase

The Advanced Phase is the time to use the skills developed in the Foundation Phase.

It's all about integrating the learning to create a Web Application, follow a few steps of the SDLC like code review and code check-in, and learn about frameworks like Spring, Hibernate, and Grails that add value in day-to-day programming activities.

5. Extras

Here, let's discuss a few other things that can give an extra edge to a Programmer in their day-to-day work:

Data Structures
Algorithms
Design Patterns
Data Formats - JSON/XML
Functional Programming - Lambda Expressions, Java Streams
Scripting - Groovy/Python

6. Conclusion

In this article, we discussed a training curriculum for Junior Programmers that aspire to be Java Full Stack Programmer and want to be productive quickly.

First, we explored the Foundation Phase that helps to develop a few skills. Then, we examined the Advanced Phase that prepares a programmer to utilize each skill learned in the Foundation Phase to be productive.

Last, we discussed some bonus concepts that can give an extra edge to a programmer over others.

Although, the curriculum is mainly targeting Java developers. However, we can replace Java with any technology like .Net, Python, and C++.

The idea is to learn the basics of a programming language with tools and methodologies that help a Full Stack Programmer be efficient, productive, and competent.

Please let me know your thoughts on the points discussed.

Thanks for reading!

Properties Of A Database Transaction

Anshul Bansal — Tue, 11 May 2021 15:53:08 +0000

1. Overview

In this short article, we'll revisit the properties of the Database Transaction.

2. What Is A Transaction?

A transaction is the unit of work performed on the database.
For example, insert/update a record in a table.

It could also contain multiple separate actions performed together but sequentially. For instance, insert a row in one table, update a row in the second table, and delete a row from another table.

A more practical example can be - adding a credit record in the Payment table and then updating the balance in the Accounts table.

3. Properties Of A Transaction

Every database transaction needs to mandatorily have a few properties to provide data reliability and integrity. These properties are called ACID.

The acronym stands for Atomicity, Consistency, Isolation, and Durability. Each property is inter-dependent and together helps to achieve data reliability and integrity.

Let's discuss them in detail to better our understanding.

3.1. Atomicity

Transactions often perform multiple separate actions.
So, a transaction that performed a few changes and missed others can result in the wrong data. Therefore, a transaction must perform every action or nothing at all. Simply put, Atomicity means all or nothing.

For instance, a transaction inserted a credit record in the Payment table and couldn't update the balance in the Accounts table (due to a failure or mishap). Then, the accounting system will result in data error, and customers could see wrong entries/calculations in their accounts.

Therefore, a transaction must ensure either all the operations are performed or rolled back all the changes.

3.2. Consistency

A transaction must always have consistent data before the start and after it ends to ensure data integrity.

If a transaction violates the database consistency rules, then the entire transaction should rollback.

For example, in a banking system, when transferring funds from one account to another, if a transaction manages to credit funds in one account and misses to debit funds from another will result in funds mismanagement. Hence, the total funds of the bank will go wrong.

3.3. Isolation

Each transaction should be isolated and performed in the total separation. So, the transactions that happen at the same time don't see each other changes until completed.

For example, suppose User A sends money to User B, and at the same time, User B sends money to User C.
Now, the transaction by User A and User B are concurrent and tries to update the balances at the same time. Therefore, both of the transactions must be isolated, not affecting each other changes and resulting in data error.

A database usually uses locking principles to achieve isolation of the transactions. In most cases, whichever transaction reaches first will get the lock of the record, performs the changes in separation. Then, another transaction requesting the lock performs the changes on the already updated data.

There are two most common database locking strategies - Optimistic and Pessimistic Locking to achieve the isolation of the transactions. We'll try to cover these in detail in another write-up.

3.4. Durability

A transaction must be durable to never undone the persisted changes even in uncertain events like power failure and abnormal termination.

Similar to our already discussed example, an application that transfers funds from one account to another, the durability property ensures the changes on the Accounts table (through a single transaction) won't be reversed in case of any mishap.

4. Conclusion

In this brief article, we briefly discussed the database transaction and its ACID properties.

Please let me know your thoughts in the comments.
Thanks for reading!

Good API Design and Why It Matters?

Anshul Bansal — Sun, 27 Dec 2020 21:45:33 +0000

1. Overview

In this article, we'll discuss How to design a Good API and Why it matters to each of us (I'm talking to the Programmers/Developers)?

Note: This article is an excerpt of Joshua Bloch's talk - How to Design a Good API and Why it Matters?

I know many of us would've already seen that video. So, we'll be going through Josh's recommendations for a Good API design and touch our basics again. By chance, if you are new, feel free to explore his genius.

2. What is an API?

An API (Application Programming Interface) is a contract between the user and the software.
It's an interface for the user to interact with the software, perform actions, and exchange data in the prescribed formats.

It can be as simple as a few methods available in a class to as complex as the web services for the enterprise software.

3. Why it Matters to Us?

Every programmer is an API designer
- Whether designing a class that performs some actions or implementing web services
Public APIs are forever, so we get only one chance to get it right
- Once APIs are published in public, it's impossible to take them back
A good API wins customers
- Assets for the corporates and lasts longer
Improves code quality, reusability, and maintainability of the software
- Good design usually coincides with good performance

4. What is a Good API?

Easy to learn
Easy to use, even without documentation
Hard to misuse
Easy to read and maintain code that uses it
Sufficiently powerful to satisfy requirements
Easy to extend and evolve
Appropriate to its audience
Coexists peacefully with the platform

5. Tips for Creating a Good API

5.1. Get the Specs Right

Start with a Short Spec - 1 Page should be Ideal
Extract true requirements out of proposed solutions

5.2. API Should Do One Thing and Do it Well

Design and implement API keeping one problem in mind.
We shouldn't try to solve a lot of problems in a single API. Better, go with a set of APIs to address different needs.

For instance, the LocalDateTime and CompletableFuture classes in Java solve the problem of Date/Time and Asynchronous programming very well.

5.3. API Should be as Small as Possible but No Smaller

Ideally, APIs should be small, simple, and clean. However, sometimes, it's easier and more rewarding to build something more general.

5.4. Don't Violate the Principle of Least Astonishment

Don't surprise the user by the behavior of APIs.
For instance, the method name and its action should be aligned mutually.

5.5. When in Doubt, Leave it Out

It's always easier to add to the API (in further iterations). But, we can't remove anything from it once published - as APIs should honor the backward compatibility to avoid any hassle for the existing implementations of the consumer.

5.6. Never Leak the Implementation Details

When implementation details get leaked through documents, it's harder to change or modify the implementations later.

For instance, a user may rely on the implementation details and use them in the features. So, this could lead to disaster on the consumer side if the implementation modifies in the APIs.

6. Implementation Guidelines for a Good API

6.1. Naming Matter

Follow naming conventions diligently. Also, names and their behaviors should be consistent throughout.
For instance, the same name shouldn't mean different in the various parts of APIs.

APIs should read like prose and never astonish the consumer by their behaviors that go against their name.

6.2. Minimize Accessibility of Everything

For instance, use Private modifiers for the variables thoroughly.

6.3. Minimize Mutability

Without a good reason, we shouldn't keep our classes mutable.
Immutable classes are simple, concise, and doesn't need synchronization handling in the concurrent transactions.

6.4. Fail Fast

Report errors as soon as possible after they occur.
Usually, compile-time is the best, and that's why we should take advantage of generics/static typings.

6.5. Use Appropriate Parameter and Return Types

Consider specific parameter types over the String. The same goes with BigDecimal over float/double for the monetary values.

Also, try to use the same parameter/return types for similar data exchange.

6.6. Avoid Long Parameter Lists

A long list of parameter lists is often confusing and error-prone when similar typed.
Ideally, it shouldn't be more than 3-4.

6.7. Use Consistent Parameter Ordering Across Methods

For ease of use, we should keep the order of the parameters similar in various actions.

6.8. Avoid Return Types that Demand Exceptional Processing

For example, when dealing with the collection return type, the consumer shouldn't bother about handling a null value, which is prone to the NullPointerException. Rather we should return an empty collection.

6.9. Documentation Matters

Documentation is a must for a good API design, its popularity, and success.

We can see, all Java APIs and popular libraries are very well documented.
Therefore, we should document everything like class, interface, method, constructor, parameter, and exception. Also, we must state the preconditions, postconditions, and side-effects for any action/behavior.

At the same time, as we've discussed already, we should never document implementation details.

6.10. Test with Two-Three Plugins Before Release

We should test our APIs very-well before the release. For that, write two to three plugins for the APIs to make sure it will mostly behave as expected for future consumption.

7. Conclusion

In this article, we've seen a few recommendations for a Good API design, some tips and tricks for the implementation, and why it matters to us?

For Coding Best Practices take a look:

Coding Best Practices for Java Apps

Anshul Bansal ・ Nov 16 '20

#java #codequality #productivity #beginners

Please share your thoughts in the comments.

Thanks for reading!

Coding Best Practices for Java Apps

Anshul Bansal — Mon, 16 Nov 2020 12:11:41 +0000

Introduction

Coding best practices are always helpful in ensuring the code quality, performance, and consistency.

In this article, I'll share a few coding best practices to follow while developing Java Applications that I use in my daily coding.

Before jumping to that, I'd recommend readers follow my other write-up that will set the stage for us:

Code Review Checklist for Java Beginners

Anshul Bansal ・ Jan 5 '20

#java #beginners #productivity #codequality

Now, we're all set to take a look at a few best practices:

Follow the OOPs principles - Abstraction, Encapsulation, Inheritance, and Polymorphism
Use Design Patterns like Singleton, Decorator, Factory, and Builder-Factory for reusable, robust, and maintainable code
Leverage the Project Lombok library to reduce boiler-plate code
Use Java Stream APIs and Lambda expressions to process collections of objects
Leverage Lambda expressions to perform functional programming in Java
Leverage Generics for cleaner code and less duplicity
Use the Collections class for performing general operations on a collection
Use the LocalDate, LocalTime, and LocalDateTime classes to work with Date/Time.
Consider Optional in place of null
Prefer Atomic variables and Concurrent Collections over Synchronization
Proper Error/Exception handling
Leverage ExecutorService for Asynchronous operations
Move the business logic to Services for reusability
Keep controllers thin - only for handling request/response
It's a better idea to reduce Database interactions
If using ORM technology like Hibernate, use Lazy/Eager fetching techniques wisely
Use a database connection pool for the handling of DB connections
Leverage batch insert/update for bulk transactions
May use asynchronous programming for long fetched queries
Try not to block the main thread for long execution task - try asynchronous programming instead using the FutureTask and CompletableFuture classes
Enable logging using SLF4J
Unit test the code using testing frameworks like JUnit
Document API specifications using Swagger 2

Summary

In this short article, we've seen a few pointers for coding best practices as well as a few tips and tricks to follow while developing Java Applications.

Please let me know your thoughts and share the best practices you follow in the comments below.

Thanks for reading!

My Programming Journey to Senior Programmer

Anshul Bansal — Sun, 18 Oct 2020 15:03:29 +0000

1. Overview

In this article, I'll speak about a list of things I tried or explored in my eight-plus years of programming.

What worked for me and what I've left on the way. What I'll continue and what I want to start in the future.

My journey as a Software Programmer started when I joined a world-renowned software services provider in 2012 as a Java - Full Stack Engineer Trainee.

Since then, I've tried numerous ways to learn, grow, and keeping myself updated/groomed in this rapidly changing industry.

2. Technical Books, Tutorials, Blogs, and Documentation

I gathered most of my knowledge, be it basics or hands-on, of programming, technologies, and frameworks through books and tutorials.

For example, books like Head First Java, Grails in Action, and Groovy in Action, tutorials like tutorialspoint, w3schools helped a lot initially.

Also, I followed a few blogs like javarevisited, dzone, baeldung, and mrhaki blog to learn core/advanced features of various technologies.

Then, the official documentation of the popular libraries/ frameworks like jQuery, Spring, Grails, and Hibernate was a big help.

Also, from the start, I committed to myself to get hands-on with any technology or skill in just two weeks using any of the resources discussed above.

Of course, mastering something is a long-time process. However, two weeks are enough to get started, be a little productive in our work, and reduce the learning curve to a modest time-frame.

It helped me a lot in all these years and will keep it going.

3. Presentations and Demo Sessions

I like to attend/host technical presentations & demo sessions. They give a quick overview of the technology/software and helps in catching up with the updates in the industry.

Also, most of the IT companies have learning programs that include webinars, sessions, and presentations that help the employees keeping themselves updated.

If there is a skill that we are good at, we should share it with others for collective growth.

For instance, I learned a great deal of Code Quality and Best practices from my seniors, design patterns, and technologies from colleagues, and the list can go on and on.

Similarly, I've hosted many hands-on sessions and presentations for various frameworks and libraries.

Therefore, to keep up with a new version/feature of technology or to learn a skill, it could be a good idea to prepare a quick presentation or hands-on project.

I believe this is something that we should do more and will keep in the loop.

4. Requirement Analysis

As my career progressed, there was a need to start analyzing new projects/features based on technical and business requirements.

Quickly I learned, it's always a good idea to analyze the product offering (software) from the end-user and client's perspective. In the long run, this helped me to become a better problem solver and grew as a leader.

It's an ever-growing process, and we should follow it with due diligence.

5. Stackoverflow

Without a doubt, I can say, all of us use StackOverflow for all our code queries or technical problems.

Then, there was a phase where I started posting answers on the StackOverflow. It worked wonders in improving my detailed knowledge of the subject (framework/technology), debugging, and problem-solving skills.

However, I couldn't continue my stint as a StackOverflow contributor for long. To follow a question and answer it with the best possible solution needed a lot of time and commitment.

6. Online Coding Problems

Online coding problems provide a great way to come out of our comfort zone and challenge ourselves with broader categories of the problem - varying from technical to real-life scenarios.

Around 5 years back, I started using a few platforms like codingame, hackerrank, and hackerearth for solving online coding problems.

Initially, I started to enjoy the journey. Then, I got obsessed with finding solutions. There was a time when I couldn't sleep well at night without finding a solution and code it through. Soon, I pitched the idea of organizing online coding battles in my company.

Solving coding problems helped all of us in improving problem-solving skills and developing the much-needed ability to follow the requirements in minute details.

Also, I was able to clear interviews with various companies, thanks to this habit.

However, now I couldn't spare much time to enjoy this activity more, but this is something that I'll continue.

7. Personal Projects and GitHub

Personal projects are a must for any budding programmer. Start with small programming sessions and gradually pick up to code through real-world problems.

In my initial days of programming, I started working on a social networking site using the Grails framework and Groovy technology.

I followed Grails in Action book to get the programming started. Along the way, I developed quite a good understanding of the Grails framework and architecture behind such complex social networking websites.

The learnings always come in handy when brainstorming for solutions behind tricky problems.

Not to mention, it's always a good idea to keep your code in Github or any public repository.

Not only it gives you a benefit to access it from anywhere, but it also improves your socio-technical profile, by which your future employer can take a look at your skills and shows interest in you.

It happens to me on many occasions that companies/managers shown interest in my Github profile by checking out my repositories.

Also, don't forget to add README files with setup and info about projects.

Try following industry standards in writing the code to have better readability and easy to follow code. Having a habit of writing code following best practices helps in the long run.

8. Client Proposals

As I grew in my career, my seniors insisted on participating in the discussions for various technical proposals/offering to the clients.

It was all about leveraging our talents to come up with the best possible solutions (within the cost) for customer satisfaction.

This kind of thing can be a good brain teaser and helps to understand the different needs of the client. With such brainstorming sessions, we can become a solution provider at various levels.

9. Writing Technical Content

In 2017, I attended a session on writing a technical book.

It opened a different world to me. I never thought of the diligence and passion required to write a technical book.

I always wanted to share my knowledge through various channels - writing technical content is one of them.

Two years ago, I came across an opportunity to write technical content for Baeldung. It improved my writing skills and provided me the opportunity to gather basic knowledge/hands-on of various technologies.

Since then, I wrote a handful of articles for the Baeldung. At the same time, I tried posting technical content on dev.to once in a while.

Writing technical content is a big commitment. However, this is something that surely I'll keep myself hooked on.

10. Thinking of an Idea for a Startup

I try to find and still finding a few problems or business ideas that can be solved using technology or a business process.

Not only this activity can make us a better observer, but this also has the potential to turn out a big thing in the future.

As we all know, everything in this industry started with an idea!

Not to mention, it's an ongoing process, and I'll continue doing it.

11. Finding Scope of Improvement

In everything I do, I know there is a scope for improvement.

Once my manager said that if you don't find any scope of improvement in your six months old code, then you haven't learned anything for six months. I truly believe in this.

As we grow and evolve in the industry, we learn new techniques, new principles, and improved ways of solving a problem.

For me, it's the core trait to be successful in this industry.

12. Things I Want to Do More and Try in Future

Thinking of an idea/business process is going to be continued. Other than usual, I want to develop an aptitude to think of the unthinkable.

Also, I want to be a contributor to open-source projects. As we all know, open-source software is so popular and is a thing of today's times.

At times, I freelanced to design/implement websites, but I should explore freelancing more and want to give more time to this activity in the future.

In simple language, I want to keep exploring, improving, and enjoying my programming.

13. Conclusion

In this article, I took you through a series of activities that I tried over my 8+ years of programming.

Many of them are very handy for most of the programmers. A few add charm to our socio-technical profile. And rest is how we want to enjoy working in this glorious industry.

I'm not telling you which ones to pick - you can decide what you would want to do and what you don't.

Feel free to share what worked for you and what not, in the comments. Thanks for reading.

Code Review Checklist for Java Beginners

Anshul Bansal — Sun, 05 Jan 2020 13:07:37 +0000

Checklists are always helpful! They provide a quick check to ensure consistency and completeness in carrying out a task efficiently and effectively.

Here, I've consolidated a basic 20 points checklist for Java Beginners to review the code. It'll help them to ensure code quality and consistency.

Without further ado... Let's go through it...

1. Null Checks

We know NullPointerException is the most common exception in Java and can cause big problems.

So, as a general practice, always do a null check on a variable before any operation.

2. Exception Handling

The try-catch block should be used for exception handling with proper logging in the catch block.

Also, make sure to close the resources properly in the finally block.

3. Code Indentation and Formatting

For a cleaner and readable code, use code indentation thoroughly (with Tab or Spaces anything).

It can be done automatically with the built-in editor of the IDE. For instance, use Ctrl-Shift-F in Eclipse. Similarly, Ctrl-Alt-L in IntelliJ.

Make use of Java formatting rules!

4. Optimize Imports

Always optimize imports in the Java class.

5. Static Code Review Tools

Use static code review tools like Sonar, PMD, and FindBugs to review the code.

6. Constants

Create a constant file for static values that are needed at multiple places
Use Database-driven values for dynamic values
Use ENUMs for a group of constants

7. Naming Conventions

Always check if the name of a variable/method/class truly covers the subject
Package names should be in all lower cases that start with reversed Internet domain name followed by application name. For example, org/companyname/appname
Class names should start with Capitals. For instance, Animal, Employee, and User
Variable/Method names should be in CamelCase. For instance animalInstanceList, calculateAmount, and displaySummary()
Try to avoid abbreviations in class/method/variable names. Prefer domainCode over dmnCd

8. Not All One-Liners

It's good to keep the code clean and readable. So, it's a better idea to not always go with one-liners. Especially, when we initialize and operate the variable in one line.

For example, write:

out.write(attrs.get("offset") + "-" + Math.min(attrs.get("count"), attrs.get("offset") + attrs.get("max")) + " " + title + " " + attrs.get("count"));

as:

int start = attrs.get("offset")
int total = attrs.get("count"))
int end = Math.min(total, start + attrs.get("max"))
out.write(start + "-" + end + " " + title + " " + total)

9. White-Spaces

Use white-spaces to separate combined statements to make code more readable.

For example, write:

Integer.valueOf(params.offset?params.offset:attrs.offset)

as:

Integer.valueOf(params.offset ? params.offset : attrs.offset)

10. Spaces Before and After Brackets

In general, we don't use white spaces in the brackets.

For example, write:

if ( params )
if ( total > 0 )
if ( end < begin )

as:

if (params)
if (total > 0)
if (end < begin)

11. Curly Braces

Use curly braces for one-liners also.

For example, write:

if ( end < begin )
    end = begin

as:

if (end < begin) {
    end = begin
}

12. Comments

Always put comments (if any) defining the purpose.

For example, Javadoc on a class:

/**
 * General convenience tags for layout - header, body and footer
 * @author – Name
 * @dateCreated - Date
 */
class LayoutTagLib {
}

Javadoc on a method:

/**
 * Gets the user for specified code and role.
 * @param code :- The code, either username or email address
 * @param role :- The role identification e.g. A, B or C. Default is A.
 * @return the user or null if not found
 */
User findUser(String code, String role = "A")

Make sure the code is self-explanatory and comments are really useful in very specific cases.

13. Clean Up

Remove console print Statements (SOPs), use logging instead (never log personal information)
Remove obsolete comments
Use the @deprecated annotation on the method/variable, if it is not meant for future use or going to be removed
Remove hardcoded variable values

14. Business Logic

Avoid redundant code by using reusable components like utilities and service methods.

15. StringBuilder or StringBuffer in Place of String

When performing a lot of operations on the String, use StringBuilder or StringBuffer

For example, Java creates a new String object for every concatenation operation. In this case, a better idea is to use a StringBuffer.

16. switch-case Over Multiple if-else

It's a good practice to use switch-case in place of multiple if-else conditions.

It optimizes the code execution and also makes code cleaner and more readable.

17. Objects Creation in a Loop

It is usually better to create the object inside the loop (If object is not required outside loop). Java optimizes memory usage for short-lived objects.

For example, write:

Person person;
for (int i=0; i<namesList.size(); i++) {
    person = new Person();
    person.setName(namesList.get(i));
    person.display();
}

as:

for (int i=0; i<namesList.size(); i++) {
    Person person = new Person();
    person.setName(namesList.get(i));
    person.display();
}

Also, create a new object only if required.

For example, write:

ArrayList<Person> personList = new ArrayList<Person>();
for (int i=0; i<namesList.size(); i++) {
    Person person = new Person();
    if (null != namesList.get(i)) {
        person.setName(namesList.get(i));
        personList.add(person);
    }
}

as:

ArrayList<Person> personList = new ArrayList<Person>();
for (int i=0; i<namesList.size(); i++) {
    if (null != namesList.get(i)) {
        Person person = new Person();
        person.setName(namesList.get(i));
        personList.add(person);
    }
}

18. Code Commit

Group the files and commit together (don't commit files in separate commits)
Don't commit the code which has the actual Password. Make sure to use a system/configuration variable to replace the password
Commit messages should contain the task information. For example, JIRA issue number, a meaningful comment on code implementation
Commit .class files (from the build, out, target directories), only if required

19. Use equals over ==

equals perform the actual comparison of two strings, whereas == compares object references.

20. Keep It Simple!

Maintain simplicity and readability of code.

Please let me know your thoughts on it.
Thanks for reading.

Create RESTful APIs using Spring Boot + Mongo DB

Anshul Bansal — Mon, 30 Dec 2019 15:36:25 +0000

1. Overview

Nowadays, a web application is often separated into two components - frontend and backend.

With the growing popularity of frontend technologies like Angular and React, backend features are often exposed as the RESTful APIs.

In this tutorial, we'll create RESTful APIs using Spring Boot. At the same time, we'll use Spring Data MongoDB to provide persistence support in our App by connecting to MongoDB.

2. Prerequisites

We need a set of standard tools:

Java 8 or later
Build Tool (Maven or Gradle)
IDE (IntelliJ or Eclipse)

We'll use a combination of Java 8, Gradle and IntelliJ for our implementation.

To quickly create the Spring Boot application, we'll use Spring Initializr. Also, we'll install and configure Mongo DB.

3. Application

Let's create RESTful APIs for a user registration app.
For simplicity, we'll just add features to perform CRUD (Create, Read, Update and Delete) operations.

Once the Spring Boot app is created, we'll create the application.properties file with MongoDB configuration details:

spring.data.mongodb.database=springboot_mongo_db

3.1. Entity

First, we'll create the User entity with basic properties like firstName, lastName, and email:

@Getter
@Setter
public class User {
    @Id
    private String id;

    private String firstName;
    private String lastName;
    private String email;
    private String phone;
    private String address;
}

Here, we've used @Id annotation to define the identifier.

At the same time, we've used @Getter and @Setter annotations provided by the Project Lombok to create getters/setters automatically.

3.2. Repository

Then, we'll create the UserRepository interface that provides basic operations on the database using Spring Data provided MongoRepository:

public interface UserRepository extends MongoRepository<User, String> {
}

3.3. Service

Next, we'll create a service class that provides the business logic for basic CRUD operations.

For this, let's create the Registration interface to define the abstraction:

public interface Registration<ID, USER> {
    USER registerUser(USER user) throws Exception;

    USER getUser(ID userId) throws Exception;

    USER updateUser(USER user) throws Exception;

    void deleteUser(ID userId) throws Exception;
}

Then, we'll create the RegistrationImpl class to implement the Registration interface:

@Service
public class RegistrationImpl implements Registration<String, User> {
    @Autowired
    private UserRepository userRepository;

    @Override
    public User registerUser(User user) throws Exception {
        user = userRepository.save(user);
        return user;
    }

    @Override
    public User getUser(String userId) throws Exception {
        User user = userRepository.findById(userId);
        return user;
    }

    public List<User> getAllUser() throws Exception {
        List<User> users = userRepository.findAll();
        return users;
    }

    @Override
    public User updateUser(User user) throws Exception {
        user = userRepository.save(user);
        return user;
    }

    @Override
    public void deleteUser(String userId) throws Exception {
        if (userId == null) {
            throw new Exception("user id is null");
        } else {
            userRepository.delete(userId);
        }
    }
}

Note that we've used @Service annotation to declare the RegistrationImpl class as a service for Spring Boot. Also, we've used @Autowired annotation to inject the UserRepository dependency.

3.4. Controller

Now that we've got entity, repository and service ready, we'll create the RegistrationController class to expose the APIs:

@RestController
public class RegistrationController {
    @Autowired
    private RegistrationImpl registrationImpl;
}

Here, we've used @RestController annotation to declare it as a RESTful API controller.

At first, we'll add a method registerUser to register the user (CREATE):

@PostMapping(path = "/registerUser")
public ResponseEntity registerUser(@RequestBody User user) throws Exception {
    HashMap<String, Object> resp = new HashMap<>();
    registrationImpl.registerUser(user);
    resp.put("user", user);
    return new ResponseEntity<>(resp, HttpStatus.OK);
}

Voila, we're ready with our first RESTful API to register the user.

Let's try it using the following curl command:

curl -X POST "http://localhost:8080/registerUser" -H "Content-Type: application/json" \
-d '{"email": "xyz@email.com", "firstName": "norman", "lastName": "lewis", "phone": "90909090"}'

Then, let's add a method getUser to search the user by id (READ):

@GetMapping("/getUser" )
public ResponseEntity getUser(@RequestParam("id") String id) throws Exception {
    User user = registrationImpl.getUser(id);
    return new ResponseEntity<>(user, HttpStatus.OK);
}

So, we can use the curl to read the user:

curl -X GET "http://localhost:8080/getUser?id=5e0a0a393844b64a1548c4d9"

Similarly, we can define a method getAllUser to fetch all the users:

@GetMapping("/getAllUser" )
public ResponseEntity getAllUser() throws Exception {
    List<User> users = registrationImpl.getAllUser();
    return new ResponseEntity<>(users, HttpStatus.OK);
}

Then, we'll add a method updateUser to update the user (UPDATE):

@PutMapping(path = "/updateUser")
public ResponseEntity updateUser(@RequestParam("id") String id, @RequestBody User user) 
throws Exception {
    HashMap<String, Object> resp = new HashMap<>();
    registrationImpl.updateUser(user);
    resp.put("user", user);
    return new ResponseEntity<>(resp, HttpStatus.OK);
}

Last, let's add a method deleteUser to delete the user (DELETE):

@DeleteMapping("/deleteUser")
public ResponseEntity deleteUser(@RequestParam("id") String id) throws Exception {
    registrationImpl.deleteUser(id);
    HashMap<String,String> resp = new HashMap<>();
    resp.put("message", "User is successfully deleted");
    return new ResponseEntity<>(resp, HttpStatus.OK);
}

3.5. Validation

Next, we'll add the feature of bean validations to our APIs using hibernate-validator.

First, we'll add the dependency to the build.gradle:

compile group: 'org.hibernate', name: 'hibernate-validator', version: '5.0.0.Final'

Then, we'll add a few annotations like @NotNull and @Email to the User entity.

public class User {
    // ...

    @NotNull(message = "First Name is mandatory")
    private String firstName;

    @NotNull(message = "Last Name is mandatory")
    private String lastName;

    @NotNull(message = "Email is mandatory")
    @Email(message = "Not valid email")
    @Indexed(unique=true)
    private String email;

    @NotNull(message = "Phone Number is mandatory")
    private String phone;    
}

Next, we'll use the ValidatingMongoEventListener to register as a bean in the main class - Application:

@SpringBootApplication
public class Application {
    @Bean
    public ValidatingMongoEventListener validatingMongoEventListener() {
        return new ValidatingMongoEventListener(validator());
    }

    @Bean
    public LocalValidatorFactoryBean validator() {
        return new LocalValidatorFactoryBean();
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

Last, we'll modify the registerUser method in the RegistrationController to validate the User object:

@PostMapping(path = "/registerUser")
public ResponseEntity registerUser(@RequestBody User user) throws Exception {
    HashMap<String, Object> resp = new HashMap<>();
    try {
        registrationImpl.registerUser(user);
    } catch (ConstraintViolationException e) {
        HashMap<String, String> messages = new HashMap<>();
        e.getConstraintViolations().stream().forEach(constraintViolation -> {
            messages.put(
                    constraintViolation.getPropertyPath().toString(),
                    constraintViolation.getMessage());
        });
        resp.put("error", true);
        resp.put("messages", messages);
    }
    resp.put("user", user);
    return new ResponseEntity<>(resp, HttpStatus.OK);
}

That's it! We're ready to examine the validation:

curl -X POST "http://localhost:8080/registerUser" -H "Content-Type: application/json" -d '{"email": "xyz@email.com"}'

Here, we've not provided firstName, lastName, and phone. So, the response will be:

{"messages":{"firstName":"First Name is mandatory","lastName":"Last Name is mandatory","phone":"Phone Number is mandatory"},"error":true,"user":{"id":null,"firstName":null,"lastName":null,"email":"xyz12@email.com","phone":null,"address":null}}

3.6. Swagger Integration

So far, we've used curl to request our APIs. Now, we'll integrate Swagger 2 documentation for our APIs using Springfox.

All we need is to add the Springfox dependencies in build.gradle:

compile "io.springfox:springfox-swagger2:2.9.2"
compile 'io.springfox:springfox-swagger-ui:2.9.2'

Then, we'll annotate the main class with @EnableSwagger2 annotation:

@EnableSwagger2
@SpringBootApplication
public class Application {

    // ...
}

That's it! Our API specifications are ready and are accessible at http://localhost:8080/swagger-ui.html.

4. Conclusion

In this tutorial, we've created RESTful APIs for the User registration App using SpringBoot and Spring Data Mongo DB.
Also, we've used Project Lombok to reduce the boiler-plate code and Springfox APIs for Swagger 2 documentation.

The entire code implementations are available over on Github

Please let me know your thoughts on it!
Thanks for reading.

Swagger-2 API documentation for Spring App using Springfox

Anshul Bansal — Mon, 16 Dec 2019 21:58:00 +0000

1. Overview

Spring is a very popular JEE framework to create web applications.

Often, we use Spring technologies to expose APIs to third-party integrations. At that time, our APIs require a detailed specification that helps in easy integrations.

In this tutorial, we'll explore the Springfox Java libraries to generate Swagger based API specifications for the Spring application.

2. Springfox

Springfox is a set of Java libraries, that has evolved from the swagger-springmvc project.

It automates the generation of specifications for JSON APIs, implemented with the Spring framework. Also, it provides libraries to integrate the Swagger UI to interact with APIs.

Springfox examines the Spring application at runtime and generates the API specifications based on configurations and annotations.

Let's explore Swagger 2 integration with Spring REST API. Also, we'll touch upon the basic configurations.

3. Setup

Let's add the latest springfox-swagger2 Maven dependency to our Spring Boot application:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

Similarly, we can add the springfox-swagger2 dependency to a Gradle based Spring project:

compile "io.springfox:springfox-swagger2:2.9.2"

4. @EnableSwagger2

Now that we've set up the Springfox dependency. Let's enable Swagger 2 to generate the API specifications.

To do so, we'll add the @EnableSwagger2 annotation to the main class of our application:

@EnableSwagger2
@SpringBootApplication
public class SpringfoxApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringfoxApplication.class, args);
    }
}

Let's start the application with the Maven command:

mvn spring-boot:run

Voila! The API specifications are ready.

As a result, we can access the specifications in the JSON format at localhost:8080/v2/api-docs:

5. Swagger UI

The API specification in the JSON format is not readable and difficult to follow. As a result, we need UI support that makes interaction with the API specifications easy.

Therefore, let's integrate the Swagger UI to our application, by adding the springfox-swagger-ui dependency into the pom.xml:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Then, we'll restart the app and access the Swagger UI at localhost:8080/swagger-ui.html:

6. Spring REST API

Let's explore the Swagger 2 integration with the Spring REST API.

First, let's create an entity named User:

@Entity
public class User{
    @Id
    private Long id;
    private String firstName;
    private int age;
    private String email;

    //getters and setters
}

Then, we'll create the UserRepository to add CRUD operations on the User entity:

@Repository
public interface UserRepository extends CrudRepository<User, Long> {
}

Now, we'll create the UserController for the REST APIs:

@Controller
@RequestMapping(value = "/api/user", produces = MediaType.APPLICATION_JSON_VALUE)
public class UserController {
    @Autowired
    private UserRepository userRepository;

    @PostMapping
    public @ResponseBody ResponseEntity<User> createUser(@RequestBody User user) {
        userRepository.save(user);
        return new ResponseEntity<>(user, HttpStatus.OK);
    }

    @GetMapping
    public @ResponseBody ResponseEntity<User> getUser(@RequestParam Long id) {
        Optional<User> user = userRepository.findById(id);
        return new ResponseEntity<>(user.get(), HttpStatus.OK);
    }
}

Now we've got the entity, repository, and controller in place. Let's integrate everything into the main class:

@SpringBootApplication
@EnableSwagger2
public class SpringfoxApplication {
    // ...
}

Then, we'll restart the application to see the changes:

Here, we can see the specifications are generated for the UserController APIs.

7. Configuration

Let's explore the basics of Springfox configuration.

We can configure the API specifications using the Docket class. For this, we should create a method in the main class registered as a bean and return a Docket instance.

Let's create a springfoxAppInfo bean method in the SpringfoxApplication:

public class SpringfoxApplication {
    //...

    @Bean
    public Docket springfoxAppInfo() {
        return new Docket(DocumentationType.SWAGGER_2)
          .groupName("Springfox-api")
          .select()
          .paths(paths())
          .build();
          .apiInfo(apiInfo());
    }

    private Predicate<String> paths() {
        return regex("/api/.*");       
    }

    private ApiInfo apiInfo() {
        return new ApiInfo(
          "Springfox API specification", 
          "Spring REST APIs", 
          "", 
          "", 
          null, 
          "License of API",
          "API license URL", 
          Collections.emptyList());
    }
}

Here, we've changed a few properties like the groupName and apiInfo. Also, we've restricted our API specifications to the /api URI paths.

Let's restart the application and check out the differences in the specifications:

Here, we can observe that the API info has changed. Also, the specification is available only for UserController based on the /api URI path mentioned.

8. Conclusion

In this article, we've explored the Springfox suite of libraries for generating specifications of the APIs, implemented using the Spring framework.

To begin with, we've created a Spring Boot application and integrate Swagger 2 APIs to create the specifications. Also, we've seen integration with the Swagger UI.

Then, we've examined ways to integrate Swagger into Spring REST APIs.

Last, we've touched upon the basics of Swagger UI configuration.

Please find the entire code implementations over on Github.

Would love to hear your thoughts on the article. Have any questions? Any feedback? Please comment!!!

Hexagonal Architecture in Java

Anshul Bansal — Sun, 15 Dec 2019 17:39:10 +0000

1. Overview

In this quick article, we'll discuss Hexagonal Architecture in Java through a practical example.

2. What is Hexagonal Architecture?

In simple words, a Hexagonal architecture separates software in two components - inside and outside, instead of conceptual layers.
The component that remains inside usually consists of application and domain layers, along with the core business logic. Whereas, the component for the outside world consists of layers like UI and Database.

The connection between the inside and outside components realizes via abstractions called ports and implementations called adapters.

3. Benefits

Flexibility - with different adapters, the software can serve multiple channels
Testability - as mocking code is easy
Purity - as the core logic remains intact

4. Hexagonal Architecture in Java

In Java, interfaces are ports and implementation classes are adapters.

Let's create a simple Spring Boot App and try to register/view Employee details using the Hexagonal Architecture.

To start with, we'll create an entity named Employee.
Then, the EmployeeService class to keep the core business logic to persist data.

Here, the Employee and EmployeeService classes are part of the inside component. Therefore, we'll create ports to expose them.

First, let's create the EmployeeUIPort interface to communicate with the front-end:

public interface EmployeeUIPort {
    @PostMapping("register")
    public void register(@RequestBody Employee request);

    @GetMapping("view/{id}")
    public Employee view(@PathVariable Integer id);
}

Then, we'll create the EmployeeDBPort interface to communicate with the database:

public interface EmployeeDBPort {
    void register(String name);

    Employee getEmployee(Integer id);
}

Last, we need adapters to connect to the ports - EmployeeUIPort and EmployeeDBPort.

Let's create the EmployeeControllerAdapter class that implements the EmployeeUIPort interface and act as a RestController. Therefore, it'll act as an adapter to connect with the front-end:

@RestController
@RequestMapping("/employee/")
public class EmployeeControllerAdapter implements EmployeeUIPort {
    @Autowired
    private EmployeeServiceAdapter employeeService;

    @Override
    public void register(@RequestBody Employee request) {
        employeeService.register(request.getName());
    }

    @Override
    public Employee view(@PathVariable Integer id) {
        Employee employee = employeeService.view(id);
        return employee;
    }
}

Then, we'll create the EmployeeServiceAdapter (or EmployeeService for simplicity) class that implements the EmployeeDBPort interface and keep it as a Spring Service. So, it'll behave as an adapter to persist data in the database:

@Service
public class EmployeeServiceAdapter implements EmployeeDBPort {
    @PersistenceContext
    private EntityManager entityManager;

    @Transactional
    @Override
    public void register(String name) {
        Employee employee = new Employee();
        employee.setName(name);

        entityManager.persist(employee);
    }

    @Override
    public Employee getEmployee(Integer id) {
        return entityManager.find(Employee.class, id);
    }
}

That's it, we've successfully separated our App into the inside and outside components.

As a result, the business logic of the app will be exposed via ports and consumed via adapters from outside.

Similarly, we can create different ports and implement multiple adapters for any core service.

For instance, Messaging Service and Content Management Service.

5. Conclusion

In this quick article, we've explored the concept of Hexagonal architecture in Java.

We've seen the core business logic (inside component) can be exposed as ports via interfaces and consumed by different adapters (outside component) through implementation classes.

This approach helps in writing clear, readable code with less dependency on external technology. However, I'd suggest using this pattern of ports and adapters selectively, rather than going full hexagonal.

Best Possible Hibernate Configuration for Batch Inserts

Anshul Bansal — Thu, 26 Sep 2019 14:10:56 +0000

Problem

In general, the hibernate entities (domains) are set to use database sequence as Id generator.
In such a case, for every insert hibernate makes two round trips to the database. It'll first make a round trip to get the next value of the sequence to set the identifier of the record. Then make another round trip to insert the record.

Assume, we want to insert 1000 records in the database. It'll result in a total of 2000 round trips to the database (1000 round trips each, to get the next value of a sequence and insert the records).

Even in a case of very low network latency, performing a few thousand inserts may require a significant amount of time.

The first major problem is to perform each insert separately.
The second major problem is to make a round trip to get the next value of the sequence every time.

Theoretical Solution

We should try to reduce the network round trips to the database for bulk inserts by batch processing of inserts.
Along with that, reduce the network round trips to get the next value of the sequence for every insert.

Hibernate Solution

First problem:

We know the obvious.

Use the JDBC batching provided by Hibernate.

Set the following properties in the hibernate configuration file.

<property name="hibernate.jdbc.batch_size" value="100"/>
<property name="hibernate.order_inserts" value="true"/>

Now, hibernate will make a batch of 100 inserts and orders them. Then, it will make a single network round trip to the database to insert 100 records.

Therefore, the initial 1000 round trips to insert the records will reduce to 10.

Second problem:

We'll use enhance sequence identifier with an optimizer strategy like pooled or pooled-lo, which provides in-memory identifiers. Therefore, they reserve ids in memory to be used later.

Let's see what a 'pooled' optimizer strategy can do!

To enable it, we'll require to set the 'INCREMENT BY' of the database sequence to 100.

Then, set the pooled optimizer strategy with increment_size = 100 in the entity:

@Id
@GenericGenerator(
    name = "sequenceGenerator",
    strategy = "org.hibernate.id.enhanced.SequenceStyleGenerator",
    parameters = {
        @Parameter(name = "sequence_name", value = "hibernate_sequence"),
        @Parameter(name = "optimizer", value = "pooled"),
        @Parameter(name = "initial_value", value = "1"),
        @Parameter(name = "increment_size", value = "100")
    }
)
@GeneratedValue(
    strategy = GenerationType.SEQUENCE,
    generator = "sequenceGenerator"
)
private Long id;

Now, hibernate will make a round trip to the database and set the sequence nextval to next 100 value. And, reserve the 100 values in memory to set the ids for the inserts.
With this approach, we'll make 1 round trip to fetch the next value of the sequence for every 100 records to insert.

Hence, the initial 1000 round trips to get the next value of the sequence will reduce to 10.

Therefore applying both of the solutions, we can reduce the round trips to just 20 for 1000 inserts.

We all may know about batch insert optimization. But, the sequence optimizer is quite a winner.
Not many of us know this kind of optimization strategy available already.

Isn't it sound cool and smart.

Guys, Please do share your thoughts with me.