DEV Community: Marinsborg.com

Learn Python functions & create a simple project

Marinsborg.com — Thu, 12 Jan 2023 20:46:31 +0000

Functions are key elements of programming. They are used in most programming languages.

Functions allow you to break your code into smaller pieces. That way your code is easier to manage and easier to understand.

Functions also enable you to reuse code in multiple places in your application. That way you save time and make your code easier to read.

In the first half of this post, we will explain what are Python functions, how to define them, and how to call them.

In the second part of this post, we will create a small application in which we will use Python functions. That way you can see functions in action.

How to define a Python function?

Python function is defined using a keyword deffollowed by the name of the function and parentheses. Inside parentheses, you define zero or more arguments.

Arguments (also called parameters) are inputs that are used inside the function to perform a specific task.

Let’s show an example of a simple Python function:

def subtract(a, b):
    result = a - b
    return result

In this example, we defined a function with the name ‘subtract’. That function takes two arguments ‘a’ and ‘b’. Then function subtracts those numbers and saves the result to a variable named result. In the last line, the function returns the result.

As you can see the code for the function goes inside a block indented under the definition line.

How to call a Python function?

Once you have defined a function, you call it by its name and pass the required arguments in the parentheses:

var result = subtract(10, 5)
print(result) #it would print 5

Keep in mind that you need to pass the arguments in the same order as in the definition of the function.

Otherwise, you will get an error or unwanted result.

Same function with different order of passed arguments:

var result = subtract(5, 10)
print(result) #it would print -5

Default values for arguments

Python functions also enable you to define a default value for each argument.

That way you can call the function without passing that argument and the function will use the default value instead.

For example:

def say_hi(name='user'):
    return "Hi " + name

sayHi("Joe") #function will return "Hi Joe"
sayHi() #function will return "Hi user"

In this example, the function ‘say_hi’ takes one argument ‘name’.

That argument has the default value of ‘user’.

This function can be called by passing an argument and it will use that value. Also, this function can be called without an argument and it will use the value ‘user’ instead.

Simple quiz game

In this part of the post, we will use the knowledge about Python functions from above and create a simple quiz game.

The quiz game will ask the user multiple questions and keep track of their score.

First, we'll need to define a list of questions and a list of answers. Here's an example:

questions = ["What is the capital of France?","What is the capital of Italy?","What is the capital of Spain?","What is the capital of Germany?"]
answers = ["Paris","Rome","Madrid","Berlin"]

Next, we'll need to use a loop to iterate through the questions and ask the user for an answer. Here's how to do that:

score = 0
for i in range(len(questions)):
    question = questions[i]
    answer = answers[i]

    user_answer = input(question)

    if user_answer == answer:
        print("Correct!")
                score += 1
    else:
        print("Incorrect. The correct answer is:", answer)
print("Your score is:", score)

This code will ask the user each of the questions in the questions list and check if their answer is correct by comparing it to the corresponding answer in the answers list.

If the user's answer is correct, it will print "Correct!", and if it is incorrect, it will print "Incorrect" and show the correct answer.

After asking all questions, it will print how many correct answers the player had.

Now let’s introduce Python functions and make this code more readable.

First, let’s create a function that will ask a question, take the user’s answer and compare it with the actual answer.

We also called .lower() function for the user’s answer and actual answer so we can ignore casing. If we did not do that, the function would return ‘False’ if the user for example typed ‘pARis’.

The function will return ‘True’ if the user answered right and ‘False’ otherwise.

def ask_question_and_check_answer(question, answer):
    """Asks the user a question and returns True if their answer is correct, False otherwise."""
    user_answer = input(question)
        user_answer = user_answer.lower()
    return user_answer == answer.lower()

For the rest of the code, let’s create a new function that will call ask_question_and_check_answer function.

def run_quiz(questions, answers):
    """Runs a quiz game with the given questions and answers."""
    score = 0
    for i in range(len(questions)):
        question = questions[i]
        answer = answers[i]

        if ask_question_and_check_answer(question, answer):
            print("Correct!")
            score += 1
        else:
            print("Incorrect. The correct answer is:", answer)
    return score

run_quiz function takes a list of questions and a list of answers as input, and uses the ask_question_and_check_answer function to ask the user each of the questions.

It keeps track of the user's score and returns the final score when the quiz is finished.

Let’s also write a function that will print the quiz result:

def pretty_print_results(score, total):
    """Prints the final results of the quiz game."""
    print("You scored", score, "out of", total)
    if score == total:
        print("Congratulations! You got a perfect score!")
    elif score / total >= 0.75:
        print("Congratulations! You passed with a high score.")
    else:
        print("Unfortunately, you did not pass. Better luck next time.")

pretty_print_results takes a score and a total as input, and prints the final results of the quiz game. You can set parameters for the score any way you like.

And in the end, you just need to call those two functions:

# Run the quiz and print the results
score = run_quiz(questions, answers)
pretty_print_results(score, len(questions))

There you have it. Simple quiz application that is created with three Python functions.

Now you can add more questions and answers or if you want a challenge you can find some quiz API and get questions and answers from there.

The complete solution is hosted on our GitHub. Feel free to download it or fork it and play with it.

Conclusion

In this post, we showed what is Python function, how to define one, and how to call it.

Functions are key elements of programming. They are used in most programming languages.

Understanding how to define and use functions is an important skill for any programmer.

If you have any question or suggestion, feel free to post it in the comments or you can find me on Twitter.

Also if you like the content and want to stay updated on the new content you can subscribe to my newsletter.

You will also get a FREE eBook - "learn programming from zero to your first Python program"

Choose the best programming language to learn first and where to learn them

Marinsborg.com — Mon, 12 Dec 2022 16:11:41 +0000

As a beginner in the world of programming, choosing the best programming language to learn first can be overwhelming. With so many options available, it's difficult to know how to start.

Luckily, there is no wrong answer. Every programming language is just a tool. With programming language, you give instructions to a computer to accomplish some task.

It is the same with cars. A car is also a tool that transport people and card from place A to place B. Can you answer what is the best car? Is it a Lambo? Or Ferrari?

What if you have four children that you need to drive somewhere? In that case, the best car is a minivan.

To really choose the best programming language, you need to consider what are your goals with programming. Do you want to have a programming career or is it just a hobby?

If it is a programming career, then it is a good idea to know what programming language is wanted in your area. Open job boards and check.

You also need to consider what kind of applications you want to work with. Do you want to make games? Or are you interested in mobile applications? Maybe web applications are your thing. Machine learning is a hot topic these days. There are so many options to choose from.

But don’t worry, in this post, we will list popular programming languages and where to learn them for free.

Python

Python is a popular, versatile language that is known for its simplicity and readability. It is a general-purpose programming language. Python has a large number of libraries that can be used for various branches of the industry.

It is a very easy language to learn, it uses indentation instead of curly braces and it does not need to use semicolons. Since it is easy to learn, it is often the language of choice of people that are not programmers like scientists, mechanical engineers, accountants, etc.

It has a large and supportive community, making it a great language for beginners to learn.

Used for: data science, data visualization, machine learning, task automation, web development (server-side), game development, etc.

Resources to learn from: Start with our eBook, Automate the boring stuff with Python

JavaScript

JavaScript or JS for short is a popular language that is used to develop interactive web pages or applications. About 97% of pages use JS on the client side to control web page behavior. It is usually used in combination with HTML and CSS for frontend development.

It also has a large number of libraries that help you easily solve various types of tasks.

Used for: frontend web development, backend web development (node.js), game development (browser games), mobile applications (react native), cross-platform desktop applications (electronjs)

Resources to learn from: eDx, The Odin Project - it is a page that offers a full-stack JavaScript path for free.

Java

(Do not confuse Java with JavaScript, they are not similar at all)

Java is an object-oriented, general-purpose programming language. Java was and still is a pretty popular language mainly because of the Java virtual machine (JVM) that enables to run Java code on many different types of devices.

It is commonly used for building large-scale, enterprise-level applications. It was also the main programming language to build Android applications until Kotlin become more popular.

Java has a syntax that is similar to C and C++ but it is not a low-level language as those two are.

Used for: web development (server-side) - good for large enterprise applications, desktop applications (Windows and Linux), mobile development (Android apps - however, Kotlin is now more popular for Android developers)

Resources to learn from: learnjavaonline.org

Kotlin

Kotlin is a general-purpose, cross-platform programming language that was developed to be used on the Java virtual machine (JVM). It was designed to be a modern and more powerful version of Java, with improved performance and more useful features for developers.

Because it runs on the JVM, Kotlin code can be used alongside existing Java code and libraries, making it a popular choice for Android app development. Many developers find Kotlin to be more concise and easier to read and write than Java, making it a good language to learn for beginners.

Used for: mobile development (Android apps, but also iOS apps), web development (server-side, similar to Java)

Resources to learn from: JetBrains Academy

C

C# is a general-purpose language that is widely used for building a variety of applications, including web, mobile, desktop, and gaming applications. C# is similar to other popular programming languages like Java. It was developed by Microsoft and in the past, it was mostly used for developing applications for Microsoft systems.

Used for: web development (server-side), desktop applications (Windows), game development (Unity), mobile development (Xamarin)

Resources to learn from: Microsoft's official page - it has a bunch of video tutorials and documentation

Golang

Golang, also known as Go, is a programming language that was developed by Google. It is a general-purpose language that is designed to be fast, simple, and easy to use.

One of the key features of Golang is its support for concurrency, which allows developers to write programs that can easily run multiple tasks at the same time. This makes it well-suited for building systems that need to handle a lot of data or traffic.

Golang is also known for its strong focus on security and reliability, making it a popular choice for building secure and robust software.

Used for: infrastructure, web development (server-side), data science, machine learning

Resources to learn from: Golang BootCamp - book that has everything you need to know to start with Golang

Swift

Swift is a programming language that was developed by Apple. It is a modern, powerful language that is used for building a wide range of applications, including iOS, macOS, watchOS, and tvOS apps.

Swift is known for being fast, easy to use, and safe, with a focus on writing clean, readable code.

Swift also has a strong focus on performance, making it well-suited for building apps that need to be fast and responsive. Many developers find Swift to be a good language to learn because it is powerful and versatile, yet still easy to understand.

Used for: mobile development (iOS) and other apps for Apple hardware

Resources to learn from: Official documentation

What would be the best programming language to learn?

If you still can’t decide, don’t worry. We would recommend starting to learn Python. It is a popular, simple, and broadly used programming language.

You can use Python for your hobby projects and later you can easily find a job if you know it.

If you change your mind in the future and want to learn some other language, you can do that easily.

The knowledge that you get learning one programming language can be applied to any other language. If you know how to drive a Ford, you’ll know how to drive Honda.

Free eBook and newsletter

If you liked this post and want to see more of this, consider subscribing to our newsletter. We only send useful, beginner friendly information and once you subscribe you will get a free eBook that helps you start with programming titled "Learn programming: from zero to your first Python program".

You can check all details here.

5 lessons for beginners I learned working 5 years in the industry

Marinsborg.com — Mon, 16 May 2022 21:03:20 +0000

Introduction

Five years ago I got my first job. Many things have changed since that. I learned a lot of new things and gained working and career experience. I changed several jobs, met many new people, and work on different kinds of projects. Today I will give you five tips from that period that you can use in your career.

Learn concepts, not definitions

After finishing school, university, or boot camp, some people still have that ‘school’ mentality when they start to work. Most of the time, at school, you are learning things to get good grades or to pass an exam. Usually, you forget most things after a few days.

This is not how you should do at your job. You don’t need to learn definitions or even read everything from documentation or books. You should understand concepts in a more general way so you can apply that knowledge in the future. You will not have any tests and you will not be fired if you don’t know the answers to everything. You will have time to learn about some things that are important for your job.

When you are reading and learning about some topic you should learn it in a way that you can easily explain that topic to somebody else. Sometimes you will have to make a presentation about your research and explain it to your team or even to the whole company. You can check any tech talk on YouTube to get a general idea about it.

Google is your friend

It really is. Everybody is using it. Whatever you don’t know, look that up on Google. Maybe don’t look up your medical symptoms, it will tell you that you are pregnant.

But seriously, knowing how to use Google is an excellent skill to have and it makes you independent of help from other people. If you are stuck on some task, try to google other people's ideas or check if somebody implemented something similar in another programming language.

If your IDE threw you some error message, you should copy it and paste it into Google. There is a high chance that others had the same error and somebody wrote a solution to that.

There are so many other things you will use Google for. I already wrote about some tips for better Googling in my previous post, you should check it up.

Learn to say NO

May is mental health awareness month and there are some things about the workplace that we need to talk about more.

It is really hard for some people to say ‘no’ without feeling anxious, guilty, bad, or uncomfortable. Especially if they just started working on a new job. People don’t want to say ‘no’ because they are afraid of other people's reactions. That is usually mentally exhausting. However, you need to know that it is not your thing to worry about how other people will react to ‘no’. If you don’t say ‘no’, people will (unknowingly) abuse that, usually for their own benefit.

Of course, I am not saying that you should say ‘no’ to everything but only to things that you know are not right and you know 100% it should be another way round.

Also, you can’t just say ‘no’ without any explanation. I would suggest you use one of two templates, depending on the situation:

No, (I won’t do that) because I think...
Yes, (I will do that) IF...

The first one is used when you know that something is wrong. In that case, you need to explain in detail why it is wrong until you prove other people wrong. You need to have good arguments about why you think something is wrong and also sometimes you can propose a better solution.

The second one is technically a ‘yes’ but you need to request conditions to be fulfilled before you start doing that. Until conditions are fulfilled, it is still ‘no’.

I will give you some examples, so it will be clear:

“No, we should not deploy the new version of the application on Friday because there is nobody in the office during the weekend in case something goes wrong.”
“No, I will not hardcode something in the database because it will probably cause problems in the future”
“Yes, I will change that button if you open a ticket for that and the designer sends me a new design.”

As you can see, you would get in trouble in the future if you said ‘yes’ in the examples. There is a high chance that things like this would repeat in the future because other people are used to that. Don’t hesitate to say ‘no’ when you think you are right. Be patient and explain your arguments in a kind way.

Don’t stay overtime voluntarily

This one is pretty simple. If your contract says that you need to work 8 hours per day then don’t stay overtime if you don’t need to. Of course, there will be times when the deadline is near and something is not done yet so your whole team will work overtime. But in that scenario, somebody asked you to work overtime and you will be compensated for that.

Staying overtime on your own rarely benefits you, even if you don’t have anything better to do. Everything can wait for the next morning. Your free time and rest are very important. Your time on this planet is a limited resource, don’t gift it to some company.

Leave for a better opportunity

This is something that I did very often. You come to some company, things are going fine at the beginning, you are enjoying your time there. However, after some time you notice that some things are not okay anymore. Things can go ‘wrong’ pretty fast. It can be poor management decisions, lack of people and overworking, low salary compared to the job market, etc.

It does not matter what is the cause of the problems. I would suggest you talk with your superiors, point to them about those problems and ask them to fix that. If they don’t fix those problems or if they promise to fix them but always delay then I would just leave.

I know that changing jobs is not the most pleasant thing in the world but you are doing that to improve your situation. This is especially important for people who stay at their first job for a long time, no matter if the situation would be better if they change the job. Don’t ignore red flags and step out of your comfort zone for a bit. The grass sometimes really is greener on the other side.

I already wrote a lot about this problem in my previous post - When is the time to change your job?

Resources

URL Shortener: Java & Spring complete tutorial

Marinsborg.com — Wed, 04 May 2022 20:16:10 +0000

Introduction

For more posts like this, follow me on Twitter

A URL shortener is a service that is used to create short links from very long URLs. Usually, short links have the size of one third or even one-fourth of the original URL, which makes them easier to type, present, or tweet. Clicking on a short link user will be automatically redirected to the original URL.

There are many URL shortening services available online, like tiny.cc, bitly.com, cutt.ly, etc. Implementing a URL shortening service is not a complex task, and it is often part of system design interviews. In this post, I will try to explain the process of implementing the service.

Theory

Before implementation, it is always a good idea to write down what it is needed to be done in the form of functional and non-functional requirements.

Functional requirements:

Users need to be able to enter a long URL. Our service should save that URL and generate a short link.
Users should have the option to enter the expiration date. After that date passed, the short link should be invalid.
Clicking on the short link should redirect the user to the original long URL.
Users should create an account to use the service. Service can have a usage limit per user*
User is allowed to create his own short link*
Service should have metrics, for example, most visited links*

Non-functional requirements:

Service should be up and running 100% of the time
Redirecting should not last longer than two seconds

*Requirements are optional

Url conversion:

Let's say that we want to have a short link with a maximum length of 7. The most important thing in a URL shortener is the conversion algorithm. URL conversion can be implemented in several different ways, and each way has its pros and cons.

One way of generating short links would be hashing the original url with some hash function (for example MD5 or SHA-2). When using a hash function it is sure that different inputs will result in different outputs. The result of the hash is longer than seven characters, so we would need to take the first seven characters. But, in this case, there could be a collision because the first seven characters could already be in use as a short link. Then, we take the next seven characters, until we find a short link that is not used.

The second way of generating a short link is by using UUIDs. The probability that a UUID will be duplicated is not zero, but it is close enough to zero to be negligible. Since a UUID has 36 characters, that means that we have the same problem as above. We should take the first seven characters and check if that combination is already in use.

Third way would be converting numbers from base 10 to base 62. A base is a number of digits or characters that can be used to represent a particular number. Base 10 are digits [0-9] which we use in everyday life and base 62 are [0-9][a-z][A-Z]. This means that, for example, number in base 10 with four digits would be the same number in base 62 but with two characters.

Using base 62 in url conversion with a maximum length of seven characters allows us to have 62^7 unique values for short links.

So how base 62 conversion works?

We have a base 10 number that we want to convert to base 62. We are going to use the following algorithm:

    while(number > 0)
    remainder = number % 62
    number = number / 62
    attach remainder to start of result collection

After that, we just need to map numbers from the result collection to the base 62 Alphabet = [0,1,2,...,a,b,c...,A,B,C,...].

Let's see how this works with a real example. In this example, let's convert 1000 from base 10 to base 62.

    1st iteration:
        number = 1000
        remainder = 1000 % 62 = 8
        number = 1000 / 62 = 16
        result list = [8]
    2nd iteration:
        number = 16
        remainder = 16 % 62 = 16
        number = 16 / 62 = 0
        result list = [16,8]
        There is no more iterations since number = 0 after 2nd iteration

Mapping [16,8] to base 62 would be g8. This means that 1000base10 = g8base62.

Converting from base 62 to base 10 is also simple:

    i = 0
    while(i < inputString lenght)
        counter = i + 1
        mapped = base62alphabet.indexOf(inputString[i]) // map character to number based on its index in alphabet
        result = result + mapped * 62^(inputString lenght - counter)
        i++

Real example:

    inputString = g8
    inputString length = 2
    i = 0
    result = 0
    1st iteration
        counter = 1
        mapped = 16 // index of g in base62alphabet is 16
        result = 0 + 16 * 62^1 = 992
    2nd iteration
        counter = 2
        mapped = 8 // index of 8 in base62alphabet is 8
        result = 992 + 8 * 62^1 = 1000

Implementation

Note: The whole solution is on my Github. I implemented this service using Spring boot and MySQL.

We are going to use our database's auto-increment feature. The auto-incrementing number is going to be used for base 62 conversion. You can use any other database that has an auto-increment feature.

First, visit Spring initializr and select Spring Web and MySql Driver. After that click on Generate button and download zip file. Unzip the file and open the project in your favorite IDE.
Every time I start a new project, I like to create some folders to logically divide my code. My folders in this case are controller, entity, service, repository, dto, and config.

Inside the entity folder, let's create a Url.java class with four attributes: id, longUrl, createdDate, expiresDate.

Notice that there is no short link attribute. We won't save short links. We are going to convert the id attribute from base 10 to base 62 every time there is a GET request. This way, we are saving space in our database.

The LongUrl attribute is the URL we should redirect to once a user accesses a short link. The created date is just to see when the longUrl is saved (it is not important) and expiresDate is there if a user wants to make a short link unavailable after some time.

Next, let's created a BaseService.java in the service folder. BaseService contains methods to convert from base 10 to base 62 and vice versa.

    private static final String allowedString = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
    private char[] allowedCharacters = allowedString.toCharArray();
    private int base = allowedCharacters.length;

Like I mentioned before, if we want to use base 62 conversions, we need to have a base 62 alphabet, which in this case, is called allowedCharacters. Also, the value of the base variable is calculated from the length of the allowed characters in case we want to change the allowed characters.

The encode method takes a number as input and returns a short link. The decode method takes a string (short link) as an input and returns a number. The algorithms should be implemented as they were explained above.

After that, inside the repository folder, let's create UrlRepository.java file, which is just an extension of JpaRepository and it gives us a lot of methods like 'findById', 'save', etc. We don't need to add anything else to this.

Then, let's create a UrlController.java file in the controller folder. The controller should have one POST method for creating short links and one GET method for redirecting to the original URL.

    @PostMapping("create-short")
    public String convertToShortUrl(@RequestBody UrlLongRequest request) {
        return urlService.convertToShortUrl(request);
    }

    @GetMapping(value = "{shortUrl}")
    public ResponseEntity<Void> getAndRedirect(@PathVariable String shortUrl) {
        var url = urlService.getOriginalUrl(shortUrl);
        return ResponseEntity.status(HttpStatus.FOUND)
        .location(URI.create(url))
        .build();
    }

POST method has a UrlLongRequest as its request body. It is just class with longUrl and expiresDate attributes.

The GET method takes a short url as a path variable and then gets and redirects to the original url.
At the top of the controller, UrlService is injected as a dependency, which will be explained next.

UrlService.java is where most logic is and is the service used by the controller. ConvertToShortUrl is used by the POST method from the controller. It just creates a new record in the database and gets an id. That id is then converted to a base 62 short link and returned to the controller.

GetOriginalUrl is a method used by the GET method from the controller. It first converts a string to base 10, and the result of that is an id. Then, it gets a record from the database by that id and throws an exception if it does not exist. After that, it returns the original URL to the controller.

And that is it for part one. In the next part I will focus on some more 'advanced' stuff.

'Advanced' topics

In this part, I will talk about Swagger documentation, dockerization of application, application cache and MySql scheduled event.

Swagger UI

Every time you develop an API, it is good to document it in some way. Documentation makes APIs easier to understand and use. The API in this project is documented using Swagger UI.

Swagger UI allows anyone to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated, with the visual documentation making it easy for back end implementation and client-side consumption.

There are several steps that we need to do to include Swagger UI in the project.

First, we need to add Maven dependencies to the pom.xml file:

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

For reference, you can see the complete pom.xml file here.
After adding the Maven dependencies, it is time to add Swagger configuration.
Inside the config folder, we need to create a new class - SwaggerConfig.java

    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {

    @Bean    
    public Docket apiDocket() {   
        return new Docket(DocumentationType.SWAGGER_2)  
            .apiInfo(metadata())    
            .select()    
            .apis(RequestHandlerSelectors.basePackage("com.amarin"))    
            .build();    
    }

    private ApiInfo metadata(){
        return new ApiInfoBuilder()
        .title("Url shortener API")    
        .description("API reference for developers")    
        .version("1.0")    
        .build();    
        }  
    }

At the top of the class, we need to add a couple of annotations.

@Configuration indicates that a class declares one or more @beans methods and may be processed by the Spring container to generate bean definitions and service requests for those beans at runtime.

@EnableSwagger2 indicates that Swagger support should be enabled.

Next, we should add Docket bean which provides the primary API configuration with sensible defaults and convenience methods for configuration.

The apiInfo() method takes the ApiInfo object where we can configure all necessary API information - otherwise, it uses some default values. To make code cleaner, we should make a private method that will configure and return the ApiInfo object and pass that method as a parameter the of apiInfo() method. In this case it is the metadata() method.

The apis() method allows us to filter packages that are being documented.

Now Swagger UI is configured and we can start documenting our API. Inside UrlController, above every endpoint, we can use @ApiOperation annotation to add description. Depending on your needs you can use some other annotations.

It is also possible to document DTOs and using @ApiModelProperty which allows you to add allowed values, descriptions, etc.

Caching

According to Wikipedia, a cache is a hardware or software component that stores data so that future requests for that data can be served faster; the data stored in a cache might be the result of an earlier computation or a copy of data stored elsewhere.

The most frequently used type of cache is in-memory cache which stores cached data in RAM. When data is requested and found in the cache, it is served from RAM instead of from a database. This way, we avoid calling costly backend when a user requests data.

A URL shortener is a type of application that has more read requests than write requests which means it is an ideal application to use cache.

To enable caching in Spring Boot application, we just need to add @EnableCaching annotation in UrlShortenerApiApplication class.

After that, in the controller we need to set the @Cachable annotation above GET method. This annotation automatically stores the result of the method call to the cache. In the @Cachable annotation, we set the value parameter which is the name of the cache and the key parameter which is the cache key. In this case for the cache key, we are going to use 'shortUrl' because we are sure it is unique. Sync parameter is set to true to ensure only a single thread is building the cache value.

And that is it - our cache is set and when we first load the URL with some short link, the result will be saved to cache and any additional call to the endpoint with the same short link will retrieve the result from the cache instead of from the database.

Dockerization

Dockerization is the process of packaging an application and its dependencies in a Docker container. Once we configure Docker container, we can easily run the application on any server or computer that supports Docker.

The first thing we need to do is to create a Dockerfile. A Dockerfile is a text file that contains all the commands a user could call on the command line to assemble an image.

    FROM openjdk:13-jdk-alpine   
    COPY ./target/url-shortener-api-0.0.1-SNAPSHOT.jar /usr/src/app/url-shortener-api-0.0.1-SNAPSHOT.jar    
    EXPOSE 8080    
    ENTRYPOINT ["java","-jar","/usr/src/app/url-shortener-api-0.0.1-SNAPSHOT.jar"]

FROM - This is where we set a base image for the build base. We are going to use OpenJDK v13 which is a free and open-source version of Java. You can find other images for your base image at Docker hub which is a place for sharing docker images.

COPY - This command copies files from the local filesystem (your computer) to the filesystem of the container at the path we specified. So we are going to copy the JAR file from the target folder to /usr/src/app folder in the container. I will explain creating the JAR file a bit later.

EXPOSE - Instruction that informs Docker that the container listens on the specified network ports at runtime. The default protocol is TCP and you can specify if you want to use UDP.

ENTRYPOINT - This instruction allows you to configure a container that will run as an executable. Here we need to specify how Docker will run out an application. The command to run an application from the .jar file is

    java -jar <app_name>.jar

so we put that 3 words in an array and that is it.

Now when we have Dockerfile we should build the image from it. But like I mentioned before, we first need to create .jar file from our project so the COPY command in Dockerfile can work properly. To create executable .jar we are going to use maven. We need to make sure we have Maven inside our pom.xml. If Maven is missing, we can add it

<build>    
    <plugins>    
        <plugin>    
            <groupId>org.springframework.boot</groupId>    
            <artifactId>spring-boot-maven-plugin</artifactId>    
        </plugin>    
    </plugins>    
</build>

After that, we should just run the command

    mvn clean package

After that is done, we can build a Docker image. We need to make sure we are in the same folder where a Dockerfile is so we can run this command

    docker build -t url-shortener:latest .

-t is used to tag an image. In our case, that means that the name of the repository will be url-shortener and a tag will be the latest. Tagging is used for the versioning of images. After that command is done, we can make sure we created an image with the command

    docker images

That will give us something like this

For the last step, we should build our images. I say images because we will also run MySQL server in a docker container. Database container will be isolated from the application container. To run MySQL server in docker container simply run

    $ docker run --name shortener -e MYSQL_ROOT_PASSWORD=my-secret-pw -d -p 3306:3306 mysql:8

You can see the documentation on Docker hub.

When we have a database running inside a container, we need to configure our application to connect to that MySQL server. Inside application.properties set spring.datasource.url to connect to the 'shortener' container.

Because we made some changes in our project it is required to pack our project into a .jar file using Maven and build the Docker image from the Dockerfile again.

Now that we have a Docker image, we should run our container. We do that with the command

    docker run -d --name url-shortener-api -p 8080:8080 --link shortener url-shortener

-d means that a Docker container runs in the background of your terminal.
--name lets you set the name of your container

-p host-port:docker-port - This is simply mapping ports on your local computer to ports inside container. In this case, we exposed port 8080 inside a container and decided to map it to our local port 8080

--link with this we link our application container with database container to allow containers to discover each other and securely transfer information about one container to another container. It is important to know that this flag is now legacy and it will be removed in the near future. Instead of links, we would need to create a network to facilitate communication between two containers.

url-shortener - is the name of the docker image we want to run.

And with this, we are done - in browser visit http://localhost:8080/swagger-ui.html

Now you can publish your image to DockerHub and easily run your application on any computer and server.

There are two more things I want to talk about to improve our Docker experience. One is multi-stage build and the other is docker-compose.

Multi-stage build

With multi-stage builds, you use multiple FROM statements in your Dockerfile. Each FROM instruction can use a different base, and each of them begins a new stage of the build. You can selectively copy artifacts from one stage to another, leaving behind everything you don’t want in the final image.

Multi-stage builds are good for us to avoid manually creating .jar files every time we make some change in our code. With multi-stage builds, we can define one stage of the build that will do the Maven package command and the other stage will copy the result from the first build to the filesystem of a Docker container.

You can see the complete Dockerfile here.

Docker-compose

Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration.

With docker-compose, we will pack our application and database into single configuration file and then run everything at once. This way we avoid running MySQL container and then linking it to the application container every time.

Docker-compose.yml is pretty much self-explanatory - first we configure MySQL container by setting image mysql v8.0 and credentials for the MySSQL server. After that, we configure the application container by setting build parameters because we need to build an image instead of pulling it like we did with MySQL. Also, we need to set that application container depends on the MySQL container.

Now we can run the whole project with only one command:
docker-compose up

MySql scheduled event

This part is optional but I think somebody might find this useful anyway. I talked about the expiration date of the short link which can be user-defined or some default value. For this problem, we can set a scheduled event inside our database. This event would run every x minutes and would delete any row from the database where the expiration date is lower than the current time. Simple as that. This works well on a small amount of data in the database.

Now I need to warn you about a couple of issues with this solution.

First - This event will remove records from the database but it will not remove data from the cache. Like we said before, the cache will not look inside the database if it can find matching data there. So even if data no longer exists in the database because we deleted it, we can still get it from the cache.

Second - In my example script I set that event runs every 2 minutes. If our database becomes huge then it could happen that event does not finish execution within its scheduling interval, the result may be multiple instances of the event executing simultaneously.