Himanshu Singh

Canvas internals and its working

Himanshu Singh — Sat, 07 May 2022 09:56:46 GMT

Thank you for dropping by, we are here to learn about the Jetpack Compose Canvas stuff. Let us be clear here, we are not going to learn how we can implement the canvas in compose. You can check that here.

In this blog, we are going to see:

What is Canvas?
How do we draw on Canvas?
What happens under the Canvas Composable function?
Something Something Something!

What is Canvas?

We can simply call it our (Android developer's) drawing sheet where we show our creativity!

Anyone can put paint on a canvas, but only a true master can bring the painting to life: Shaun Jeffery

In our terms, our phone's real estate is the canvas for us and we bring the designer's imaginations to reality. We draw the custom UI to make it useable to the users.

How do we draw on Canvas?

Let us be clear to start with, Compose's canvas is drawing on top of View's canvas itself!

In Jetpack Compose, we use the composable to draw any kind of UI. For eg:

Text(text = "Hey Compose!")

So, in terms of compose, we use two different ways to draw custom drawings. Let's see them one by one.

Box(modifier = Modifier.drawBehind {   // Drawing goes here (1)}) {  // UI (2)}

Here, we can use drawBehind to draw our custom UI and it be drawn behind the layout (1). If we keep the Box's UI (2) empty then all the drawing be drawn same like Canvas.

Second way to draw custom UI is to use Canvas composable itself. For eg:

Canvas(modifier = Modifier) { // Drawing goes here}

Here, we do not need a drawBehind function to draw something. Right?

Let us hold on for a moment to this conclusion.

What happens under the Canvas Composable function?

Canvas and drawBehind expose the DrawScope that helps us to draw the UI we want.

DrawScope gives us the freedom to use its different functions like drawCircle, drawLine, etc to draw without excessive need to understand things about it (Let's talk about the DrawScope a tad later).

When Canvas draws the UI, it uses drawBehind function (we saw above) itself to do the thing 🙈

@Composablefun Canvas(modifier: Modifier, onDraw: DrawScope.() -> Unit) =    Spacer(modifier.drawBehind(onDraw))

Here, Canvas takes Spacer composable and passes the reference of modifier, and adds the drawBehind on the modifier and takes the onDraw to draw. Spacer composable is nothing but a composable that is used to add a space based on the size passed on using the Modifier like fillMaxSize or using size.

So, in a simply, we can say Canvas is like a wrapper composable on top of Spacer.

Let's move on.

Now, we have to understand what the drawBehind functions do so that we can understand the internal implementation.

drawBehind()

fun Modifier.drawBehind(    onDraw: DrawScope.() -> Unit) = this.then(    DrawBackgroundModifier(        onDraw = onDraw,        inspectorInfo = debugInspectorInfo {            name = "drawBehind"            properties["onDraw"] = onDraw        }    ))

drawBehind is a generic extension function that takes the DrawScope and creates an object of DrawBackgroundModifier class which is an implementation of DrawModifier and passes the onDraw and an inspectorInfo.

InspectorInfo in this case, is used to handle the information for the Canvas.

But what is this DrawScope here? Is it just a lambda? Answer is NO!

Now is the time to check upon our DrawScope!

As discussed earlier, we know DrawScope enables us with its power to do custom drawings and shapes right. It also provides us with a bit more information and details about the Canvas we will be drawing onto.

Basically, it stands by the name of providing us the scope for drawing like DrawContext, Size, Center info and LayoutDirection.

Here, DrawContext is the main player in entire canvas tbh!

Size is coming from:

    val size: Size        get() = drawContext.size

and the same way center looks,

val center: Offset        get() = drawContext.size.center

So, Since we can see the drawContext has access to size, in the same way it has the access to a Canvas variable that is the part of,

androidx.compose.ui.graphics.Canvas

Here, Canvas is the interface with functions like save, restore, translate, etc. In the same package, we have a,

internal expect fun ActualCanvas(image: ImageBitmap): Canvas

expect is used to have an actual implementation for platform-specific things.

that is used to create a new instance for Canvas function by implementing the Canvas interface present in drawContext that has an ImageBitmap like,

fun Canvas(image: ImageBitmap): Canvas = ActualCanvas(image)

and similarly, we have other expected class like:

expect class NativeCanvas

Now, these two expect have their actual implementation like:

actual typealias NativeCanvas = android.graphics.Canvas

and

internal actual fun ActualCanvas(image: ImageBitmap): Canvas =    AndroidCanvas().apply {        internalCanvas = android.graphics.Canvas(image.asAndroidBitmap())    }

Wooffff! Too many and multiple types of canvas.

Let's talk about AndroidCanvas class then here!

Here, AndroidCanvas is a class implementing the Canvas interface and overrides all its functions of it like save and restore.

But more than that, it has an internalCanvas variable that is of the View type canvas and which is assigned to the Canvas in the ActualCanvas function above.

So, now in the AndroidCanvas class, we use internalCanvas to access all the internal methods like drawArc, drawCircle, etc like,

override fun drawCircle(center: Offset, radius: Float, paint: Paint) {        internalCanvas.drawCircle(            center.x,            center.y,            radius,            paint.asFrameworkPaint()        )}

Over the top, Canvas is just a wrapper Composable function that utilizes the native Canvas to draw.

This is how we can see Compose's Canvas uses the internal Canvas and its properties to let us draw things and make the work.

Paint in Canvas Compose.

Now, in the above code snippet we do see, to draw a circle we do need a paint reference. Paint is used to provide all the visual elements like colors, etc.

Paint is also present in the View's canvas and has been used extensively there. But in Compose's Canvas, we have an Interface Paint that is mapped to the Native Paint.

Internally it is designed the same way as the Canvas, where Paint is an interface like:

interface Paint {}

Where, it has all the property variables of a paint. like alpha, blendMode etc. To our notice, it also has a function called asFrameworkPaint() that will be used to access the Paint from android.graphics.Paint package.

But, in the same file Paint.kt we have some more expectvariables like we had in the case of Canvas.

Here, the variables are:

expect class NativePaintexpect fun Paint(): Paint

These variables are provided the value using actual keyword in the same package but in a different file i.e. AndroidPaint.android.kt like:

actual typealias NativePaint = android.graphics.Paintactual fun Paint(): Paint = AndroidPaint()

Here if we see, NativePaint is given the value of the Native Paint that we have in the pre-Compose era and we assigned an object to the paint function that implements the Paint interface.

And the rest of all the values of Paint in compose we assigned from Paint in android.graphics package.

That is all for the blog, and let's keep learning.

Let's catch up on Twitter!

]]>

Canvas: How to draw text in Jetpack Compose?

Himanshu Singh — Thu, 06 Jan 2022 00:22:52 GMT

I am writing after ages and it seems the world has taken a huge leap in Jetpack Compose where Compose needs no introduction in the Android ecosystem.

With Compose, designing UI has become easy and fun. You can create almost anything using out of the box solution in compose. But as engineers, sometimes you get a design that has to be drawn and designs that are not present in Compose UI kit. Here, comes the use of Canvas and its features.

Canvas is like an art book for developers where we can create our expected masterpiece.

Canvas in Android lets us create a custom shape, fill colors to them and create crazy stuff. But when it comes to drawing a text in compose's canvas, you don't have an out-of-the-box solution to draw a text.

Enough of theory, let us see how can you drawText using Jetpack Compose's canvas. In this blog, you will see,

Basic intro to Canvas.
How to draw different shapes on Canvas using Compose?
How to draw text in Canvas?

Intro to Canvas

Canvas in Android devices is nothing but your screen. Anything that you want to show a user in your device is basically you are showing it in canvas.

So, basically, a phone's screen real-estate is the canvas for a developer to paint its masterpiece.

Canvas works in the co-ordinate system, like how you had back in your school days. X-Axis and Y-Axis.

Canvas in mobile looks like,

How to draw different shapes on Canvas using Compose?

It is very straightforward to draw on the Canvas of your phone using Compose.

To draw in canvas you need to create Canvas composable, that takes Modifier as a parameter and onDraw is the lambda inside which you are going to draw your shapes.

It looks like,

@Composablefun CanvasDemo() {    Canvas(modifier = Modifier, onDraw = {})}

Now, from here onwards whatever you draw will be in onDraw function as it has the DrawScope. Let us see few small basic shapes that can be drawn.

1. Line

drawLine(                color = Color.Blue,                start = Offset.Zero,                end = Offset(size.width, size.height),                strokeWidth = 10f            )

Here, inside onDraw, you can call drawLine directly to draw line from (0,0) i.e Offset.Zero and (x,y). You can see the reference above in the image. Here, Offset takes co-ordinates of point to draw a line.

Size here gives us the dimensions of the canvasThe output of the above line is,

2. Circle

drawCircle(                color = Color.Blue,                center = Offset(size.width / 2, size.height / 2),            )

Here, inside onDraw, you can call drawCircle with color and center. By default the center is the center of screen but here you have passed on the explicit one which is also the center of the screen.

The output looks like,

In similar way, you can draw arc, path, rectangle etc. This is just a refresher how you can draw shapes in Canvas.

How to draw text in Canvas?

Now, here comes the best part. Like the way how you can create different shapes in compose's canvas you can't draw text in it.

But, it was easily possible in Android's XML View system where you had a function called drawText and using that you could draw any text you want.

To do the same in this ecosystem, you will be utilising the same but in different way.

 drawContext.canvas.nativeCanvas.apply {                drawText(                    "Hey, Himanshu",                    size.width / 2,                    size.height / 2,                    Paint().apply {                        textSize = 100                        color = Color.BLUE                        textAlign = Paint.Align.CENTER                    }                )            }

Here,

drawContext is responsible to have all the dependency you need to create your drawing.
canvas gives access to the canvas you want to draw into.
nativeCanvas gives the instance of the native Canvas interface.

Since, you can access the canvas directly you can now use it's drawText method with the Paint object and using it you can create your expected design.

The output looks like,

PS: You can also use drawIntoCanvas in place of drawContext.canvas and it will work fine.

This is how you can drawText in your canvas using Jetpack Compose.

Let's keep in touch. Follow me here .

]]>

Building URL Shortening Service frontend - P4

Himanshu Singh — Sun, 04 Jul 2021 19:59:05 GMT

This is the last part of the series(an optional one). In this one, you are going to build a basic form using HTML using Kotlin.HTML template engine.

This is going to be a very rudimentary blog of building a frontend without any style (like CSS). It would be a very basic HTML form.

In this blog, you are going to learn,

Setting up Kotlin.HTML in the project.
Setting up the project
Building an HTML form using Kotlin.HTML.
Submitting the form to a dedicated API route.
Final Steps

Setting up Kotlin.HTML in the project.

To integrate Kotlin.HTML in your project, add the following dependency to your build.gradle.kts like,

implementation("io.ktor:ktor-html-builder:$ktor_version")

This will help you to use HTML in a DSL way in the project.

Setting up the project

You have already built, the url feature in the project. For this, create a new package called frontend,

features -> frontend -> views

and in that, you are going to have views and a file called FrontendRouting.

Basically, you are going to build one new route to submit the data using the HTML form, and using that route itself, you will fetch the response as well.

Here, let us add another route in the UrlEntity as,

const val FORM_URL = "/v1/form"

And using this URL, create another Location known as FormUrlLocation which looks like,

@KtorExperimentalLocationsAPI@Location(UrlEntity.FORM_URL)class FormUrlLocation

You don't need to create any other use case for this as you are going to use CreateShortUrlUseCase to create your short URL.

Create two files LandingPage and ResponsePage in the views folder. Here, LandingPage will have the HTML form and ResponsePage will show the shortened URL using HTML.

Building an HTML form using Kotlin.HTML

Firstly, create an Application's extension function landingPage and inside this, you will have a routing function like,

fun Application.landingPage() {    routing {    }}

You will create your Kotlin.HTML form inside the routing function with a GET call and a route like,

 routing {        get("/") {           //the HTML form will be rendered here        }    }

The above block of code means, that the default page of the base URL will open this form. For Eg. https://himashoe.com/ will open the form.

Now, let us render the form. For this, use call.respondHtml like,

 call.respondHtml {                head {                    title {                        +"Welcome to URL Shortener"                    }                }                body {                    form(                        action = UrlEntity.FORM_URL,                        method = FormMethod.post,                    ) {                        label {                            input(                                type = InputType.url,                                name = "url",                            ) {                                placeholder = "Enter your url"                                required = true                            }                        }                        button(                            classes = "primary",                            type = ButtonType.submit,                        ) {                            +"Shorten"                        }                    }                }            }

Here, inside the block, you have head and inside that, you have title which is responsible for adding that title "Welcome to URL Shortener" to the Browser tab-like

Then you have the body function, which renders a form with an input field and a button.

The form takes action and method as parameters where action represents the endpoint the data has to be submitted and method means the HTTP method which in your case is UrlEntity.FORM_URL and POST respectively.

In the input field, you have the type of data you need, i.e URL. You can also have other options like Number, date, etc. and other is name which is set to "url". The value of this form will be set like,

url: " the input data"

And, at last, you have a placeholder which means what to show if the form is empty and required which means it's mandatory to have data there before pressing the button.

With that being said, you have Button with type = ButtonType.submit and text on Button is Shorten.

The form looks like,

Submitting the form to a dedicated API route

Now, create an Application's extension function responsePage with parameters DomainProvider and ExceptionProvider like,

fun Application.responsePage(domainProvider: DomainProvider, exceptionProvider: ExceptionProvider) {    routing {    }}

Inside routing, use the FormUrlLocation to create a POST request and inside that render the HTML based on the response. This FormUrlLocation acts as the API you used in the above step to submit the form.Hence, you will receive the url in this POST request.

Using the location the POST request looks like,

  routing {        post<FormUrlLocation> {        }    }

Inside this, you have to receive the url parameter which you are passing from the HTML form.

To receive the parameters in the route, use:

  val params = call.receiveParameters()

and using this you can get the url params like:

val params = call.receiveParameters()val url = params["url"] ?: ""

Here, url variable holds the url parameter coming from the form.

Now, you need to do nothing new. You will do what you did early by first validating and then passing it to the use case.

Now, the complete code of the POST request using FormUrlLocation looks like:

  post<FormUrlLocation> {            val params = call.receiveParameters()            val url = params["url"] ?: ""            if (isValid(url)) {                val response =                    domainProvider.provideCreateShortUrlUseCase().invoke(url)                call.respondHtml {                    body {                        p {                            if (response is SuccessResponse) {                                +"Short url is: /${response.data}"                            }                        }                    }                }            } else {                call.respond(                    HttpStatusCode.BadRequest,                    exceptionProvider.respondWithGenericException("Url is not valid!")                )            }        }

Here, if you see first you are validating the url. If the URL is valid then pass it to the CreateShortUrlUseCase using the domainProvider.

If the response is successful, then render it in HTML using call.respondHtml and print it in Paragraph.

The response on the browser looks like, if you pass the https://himanshoe.com/series/short-url-service URL in the form,

Final steps

As the final steps, register both the routes in FrontendRouting file, like:

fun Application.frontendRouting(domainLocator: DomainProvider, provideExceptionProvider: ExceptionProvider) {    routing {        landingPage()        responsePage(domainLocator, provideExceptionProvider)    }}

and finally register the frontendRouting in the configureRouting function like:

fun Application.configureRouting() {    install(Locations)    routing {        frontendRouting(domainLocator.provideDomainProvider(), exceptionLocator.provideExceptionProvider())        urlRoutes(domainLocator.provideDomainProvider(), exceptionLocator.provideExceptionProvider())    }}

Here, now in configureRouting you can see that both of your routes for URL and frontend are registered.

Rest all the things remain the same in the project.

This is all about building your own URL Shortening Service using Ktor. This is just a sample to showcase how to use the template engine in Ktor.

If you like the series, do share it with people :)

Check the code here.

https://github.com/hi-manshu/ktor-url-shortener

Thank you for reading :) Hope you learned something from my experience.

If you have anything more to discuss, I will be happy to get connected at hi_man_shoe.

]]>

System Design: Build URL Shortening Service using Ktor (Part-3)

Himanshu Singh — Sun, 04 Jul 2021 18:24:55 GMT

This is the third part of the series. Check out the series here.

https://himanshoe.com/series/short-url-service

Till now you have built the url feature, the DI, and the providers. You have built all the use cases and that will be used not in routing.

You have built three use cases, i.e CreateShortUrlUseCase, FindShortUrlUseCase and FindUrlHitCountUseCase.

Now using this you will build your routes.

In this blog, you are going to learn how to use routing and locations to complete your app.

Let us start before any delay.

Setup Location.

Now, you need to have two routes basically. One for creating short URLs and one for using that routes.

Basically, like /v1/url which will be POST, and other /{url} which will be GET. Additionally, you will also create one more route to get the hit counts of the short URL.

First, create a companion object in the UrlEntity to create endpoints.

data class UrlEntity(    @BsonId    val urlId: String = ObjectId().toString(),    val originalUrl: String,    val shortUrl: String,    val createdAt: String,    val urlHitCount: Int = 0) {    companion object {        const val URL = "/v1/url"        const val URL_COUNT = "/v1/{url}/count"        const val SHORT_URL = "/{url}"    }}

I use this as my recommended way to create endpoints.

Now, you will create Locations for these routes. If you want to learn more about Location and Routine check the following post.

https://himanshoe.com/routing-in-ktor

Create a package routing in,

feature -> url -> routing

In this create two files, UrlRouting and UrlLocation.

In the UrlLocation file, create a location for:

Creating a short URL.

@KtorExperimentalLocationsAPI@Location(UrlEntity.URL)class UrlLocation

Here, you can see, UrlLocation does not take any parameter as it will take the body params.

Using short URL

@KtorExperimentalLocationsAPI@Location(UrlEntity.SHORT_URL)data class ShortUrlLocation(val url: String)

Here, ShortUrlLocation takes a param url which will act as a path parameter for /{url} route.

Short URL Count

@KtorExperimentalLocationsAPI@Location(UrlEntity.URL_COUNT)data class UrlCount(val url: String)

This will also take a param url which will act as a path parameter for /v1/{url}/count route.

You are done here setting up the Location for your app.

Setup Routing.

Now using these locations, you are going to setup your routing in the UrlRouting, which is an extension function, looks like,

fun Application.urlRoutes() {    routing {        post<UrlLocation> {        }        get<ShortUrlLocation> { request ->        }        get<UrlCount> { request ->        }    }}

You are going to setup all the logic here where you need to use use-cases to do the transaction between the user and the DB.

As a parameter, you need to pass, DomainProvider and ExceptionProvider to the urlRoutes extension function.

The update code will look like,

fun Application.urlRoutes(domainProvider: DomainProvider, exceptionProvider: ExceptionProvider) {}

UrlLocation

Let us talk about UrlLocation first.

This is a post request and here you are going to pass the data in the body. The request will look like this,

{  "url" : "my_url_which_has_to_be_shortened"}

To fetch this body, you use,

val urlRequest = call.receive<UrlRequest>()

where UrlRequest looks like,

data class UrlRequest(val url: String)

which is mapper to the above JSON.

Now, you need to check that the url which you are passing is valid or not. For that create is isValid in Util.kt and that looks like,

fun isValid(url: String?): Boolean {    return try {        URL(url).toURI()        true    } catch (e: Exception) {        false    }}

Now, the updated code of the UrlLocation, will look like,

post<UrlLocation> {   val urlRequest = call.receive<UrlRequest>()   if (isValid(urlRequest.url)) {       val response =                    domainProvider.provideCreateShortUrlUseCase().invoke(urlRequest.url)        call.respond(response)   } else {         call.respond(               HttpStatusCode.BadRequest,               exceptionProvider.respondWithGenericException("Url is not valid!")        )    }}

Here, isValid is checking for the request URL. If that is valid use domainProvider to use that specific CreateShortUrlUseCase and will respond that response to the user.

and if it's invalid, return the exception using exceptionProvider with a BadRequest status code.

ShortUrlLocation

In this, you have to use FindShortUrlUseCase to invoke the request in the path to generating a short URL. The updated code,

get<ShortUrlLocation> { request ->     val shortUrl = request.url     val response = domainProvider.provideFindShortUrlUseCase().invoke(shortUrl)     when {         response != null -> call.respondRedirect(response)         else -> call.respond(               HttpStatusCode.NotFound,               exceptionProvider.respondWithNotFoundException("Url not found!!!")          )      }}

UrlCount

In this, you have to use FindUrlHitCountUseCase to invoke the request in the path to get the count of short URLs.

The updated code look like,

get<UrlCount> { request ->    val shortUrl = request.url    val response = domainProvider.provideFindUrlHitCountUseCase().invoke(shortUrl)    call.respond(response)}

You are done setting up all the routes you require for the project. As the last step, we have the urlRoutes extension function which we need to register in the configureRouting() extension function.

val domainLocator = DomainLocatorval exceptionLocator = ExceptionLocatorfun Application.configureRouting() {    install(Locations)    routing {        urlRoutes(domainLocator.provideDomainProvider(), exceptionLocator.provideExceptionProvider())    }}

At last, we need to register all the Application extensions functions in the Application file's module like,

fun main(args: Array<String>): Unit =    io.ktor.server.netty.EngineMain.main(args)fun Application.module() {    configureStatusPages()    configureRouting()    configureSerialization()}

Here, configureStatusPages() in extension in the,

base -> Status

and configureSerialization() is the extension in the,

base -> Serialization

configureSerialization() looks like,

fun Application.configureSerialization() {    install(ContentNegotiation) {        gson {            setPrettyPrinting()        }    }}

In this configureSerialization(), we install ContentNegotiation which helps in serialization of the JSON request and response.

This is all that we have to need to create our own URL Shortening Service.

Definitely, we can add a lot of other things to this like,

Having an expiry time to the short URL.

If you like the series, do share it with folks who want to read and learn :)

Check the code here.

https://github.com/hi-manshu/ktor-url-shortener

Thank you for reading :) Hope you learned something from my experience.

If you have anything more to discuss, I will be happy to get connected on twitter.

]]>

System Design: Build URL Shortening Service using Ktor (Part-2)

Himanshu Singh — Sun, 04 Jul 2021 16:01:11 GMT

Welcome to part - 2 of the system design series of building your own URL Shortening Service. You can check Part: 1 here,

https://himanshoe.com/build-url-shortening-service-using-ktor-part-1

Till now, you have built your service and database. In this part, you will build,

Exception handling
Repository layer
Domain layer

Let us start before any delay.

Setting up Exception Handling

If you remember you have Status selected as a feature for this project. Status is responsible to handle any exception.

First, create a file called Status in,

base -> Status

This will have an extension function configureStatusPages and will look like,

fun Application.configureStatusPages() {    install(StatusPages) {        exception<NotFoundException> { cause ->            call.respond(ExceptionResponse(HttpStatusCode.NotFound, cause.message.toString()))        }        exception<SomethingWentWrongException> { cause ->            call.respond(ExceptionResponse(HttpStatusCode.InternalServerError, cause.message.toString()))        }    }}class NotFoundException(message: String?) : RuntimeException(message)class SomethingWentWrongException(message: String = "Something went wrong!") : RuntimeException(message)data class ExceptionResponse(val code: HttpStatusCode, val message: String? = null)

Here, create two custom Exception classes and the ExceptionResponse class to return as output. Then install the StatusPages and inside the block, which will handle both our custom exceptions.

This basically means if you throw any of these exceptions the above responses will be triggered of type ExceptionResponse.

Now, you have your StatusPages successfully setup. As a next step, you need to create its provider same as how you did for UrlService in the following package,

base -> provider -> exception

In the exception package, create two files named ExceptionProvider and ExceptionProviderImpl`.

The ExceptionProvider interface looks like,

interface ExceptionProvider {    fun respondWithNotFoundException(message: String?): Exception    fun respondWithGenericException(message: String?): Exception    fun respondWithSomethingWentWrongException(): Exception}

Lastly, the implementation class, ExceptionProviderImpl will look like,

class ExceptionProviderImpl : ExceptionProvider {    override fun respondWithNotFoundException(message: String?): Exception {        return NotFoundException(message)    }    override fun respondWithGenericException(message: String?): Exception {        return Exception(message)    }    override fun respondWithSomethingWentWrongException(): Exception {        return SomethingWentWrongException()    }}

ExceptionProvider will be responsible for throwing errors in the repository layer.

As a last step, you need to create is Locator in di package called ExceptionLocator. This locator will look like,

object ExceptionLocator {    fun provideExceptionProvider(): ExceptionProvider {        return ExceptionProviderImpl()    }}

You are done setting up everything you need for exception handling.

Now, let us setup our repository layer.

Setting up Repository Layer

First, create a repository package like,

feature -> url -> repository

Now, inside this as well you will create two files UrlRepository and UrlRepositoryImpl same as the service package.

Repository layer is like a link between Service and Domain layer.

UrlRepository is an interface which looks like,

interface UrlRepository {    suspend fun createShortUrl(originUrl: String): BaseResponse<Any>    suspend fun findOriginalUrl(shortUrl: String): String?    suspend fun getTotalCount(shortUrl: String): BaseResponse<Any>}

Here, you can see we have BaseResponse as return type which is present in,

util -> Response

and it looks like,

interface BaseResponse<T : Any>data class SuccessResponse<T : Any>(    val statusCode: HttpStatusCode,    val data: T? = null,) : BaseResponse<T>data class UnSuccessResponse<T : Any>(    val statusCode: HttpStatusCode,    val exception: T? = null,) : BaseResponse<T>

Here, the two data classes are responsible for handling success and failure states. They both are of BaseResponse type.

These functions are responsible for having the execution and checks before hitting the database layer.

Now, implement the UrlRepository to UrlRepositoryImpl class like same as how you did with UrlService interface.

UrlRepositoryImpl class now looks like,

class UrlRepositoryImpl(    private val urlService: UrlService,    private val exceptionProvider: ExceptionProvider) : UrlRepository {    override suspend fun createShortUrl(originUrl: String): BaseResponse<Any> {        val url = urlService.findShortUrl(originUrl)        return if (url != null) {            SuccessResponse(HttpStatusCode.Found, url)        } else {            val newShortUrl = urlService.createShortUrl(originUrl)            SuccessResponse(HttpStatusCode.Created, newShortUrl)        }    }    override suspend fun findOriginalUrl(shortUrl: String): String? {        return urlService.findOriginalUrl(shortUrl)    }    override suspend fun getTotalCount(shortUrl: String): BaseResponse<Any> {        val count = urlService.getTotalCount(shortUrl)        if (count != null) {            return SuccessResponse(HttpStatusCode.OK, count)        } else {            throw exceptionProvider.respondWithNotFoundException("Url not found!")        }    }}

Here, you can see our class takes two parameters i.e. our UrlService interface and ExceptionProvider interface to follow the principle of passing the dependency from outside.

In the createShortUrl, take the original/long URL and first check in the database if it's present or not using findShortUrl.

If it's present you just return SuccessResponse with Found HTTP Code or create a new short URL of that original URL and return SuccessResponse with Created HTTP Code.

All of these functions are exposed via the UrlService interface and as mentioned in the previous blog, you are not exposing the implementation of the Service but only the methods/functions.

In the getTotalCount function, you want to check the total number of times the short URL was used by the users you can first check if the short URL is present or not. If it's present then do our operation as normal but when you don't find it, just throw an exception using the ExceptionProvider interface.

The implementation of the UrlRepository is done. But something is left 🤭

Guessed it right!!! The DI part is left.

For that, first create a package in,

base -> provider -> repository

And create two files, RepositoryProvider and RepositoryProviderImpl.

The ReposityProvider will hold the method of our UrlRepository like,

interface RepositoryProvider {    fun provideUrlRepository(): UrlRepository}

RepositoryProviderImpl will now implement the RepositoryProvider interface like,

class RepositoryProviderImpl(private val serviceLocator: ServiceLocator) : RepositoryProvider {    override fun provideUrlRepository(): UrlRepository {    }}

If you look closely, you have ServiceLocator as a constructor parameter for our RepositoryProviderImpl class.

This Service locator will be responsible for passing the UrlServce to the UrlRepositoryImpl class from outside.

Now, the complete code looks like,

class RepositoryProviderImpl(private val serviceLocator: ServiceLocator) : RepositoryProvider {    override fun provideUrlRepository(): UrlRepository {        return RepositoryLocator.provideUrlRepository(            serviceLocator.provideUrlService()        )    }}

Here, the repository implementation is coming from the RepositoryLocator. Now you need to create the RepositoryLocator which will be present in,

di -> RepositoryLocator

The RepositoryLocator looks like,

object RepositoryLocator {    fun provideUrlRepository(urlService: UrlService): UrlRepository {        return UrlRepositoryImpl(urlService,ExceptionLocator.provideExceptionProvider())    }    fun provideRepositoryProvider(): RepositoryProvider {        return RepositoryProviderImpl(ServiceLocator)    }}

Here, provideUrlRepository returns the instance of UrlRepository and provideRepositoryProvider returns the instance of RepositoryProvider. These functions are responsible for providing the Repository wherever required.

Now, you have your Repository setup as well.

Lastly, the layer left is the domain layer. Once this is done, you can just plug the routes and things will start coming out nicely.

Setting up the domain layer.

Domain layer in any project is platform-independent and is only language-based.

In your case, the Domain layer is JVM-based and will be exposed to the routes and will be responsible for taking requests and responding as the response.

In the UrlRepository, you have 3 functions. So, for the domain layer, you will create the UseCases. But first, create a BaseUseCase which will be extended by all the use cases.Create a BaseUse case in,

base -> BaseUseCase

and it looks like,

/** A Use Case that takes an argument and returns a result. */interface BaseUseCase<in I, R : Any> {    /** Executes this use case with given input. */    suspend operator fun invoke(input: I): BaseResponse<R>}

This interface, will take an input and return an output or type BaseResponse. You are going to extend this to all the use cases where possible.

Now, as a next step create a package in,

feature -> url -> domain

And as the first UseCase, create a file CreateShortUrlUseCase and extend it using BaseUseCase. This use case will take a URL as an input and will return BaseResponse<Any>.

Also, pass the UrlRepository as the constructor parameter because they will be responsible for passing the methods to the UseCase.

The CreateShortUrlUseCase looks like,

class CreateShortUrlUseCase(private val urlRepository: UrlRepository) : BaseUseCase<String, Any> {    /** Executes this use case with given input. */    override suspend fun invoke(input: String): BaseResponse<Any> {        return urlRepository.createShortUrl(input)    }}

Here, the return statement is passing the createShortUrl function from the repository as it was of BaseReponse<Any> return type as well.

Similarly, create FindUrlHitCountUseCase in the same package. The implementation you will see would be the same as the above with only the return function being changed from the repository.FindUrlHitCountUseCase looks like,

class FindUrlHitCountUseCase(private val urlRepository: UrlRepository):BaseUseCase<String,Any> {    /** Executes this use case with given input. */    override suspend fun invoke(input: String): BaseResponse<Any> {        return urlRepository.getTotalCount(input)    }}

Now, as you have 3 functions in your repository and you created two use cases. You are left with one, i.e.

    suspend fun findOriginalUrl(shortUrl: String): String?

You can see here, it doesn't have BaseResponse as return type but String as return value. Now, create a use case for this that will be called FindShortUrlUseCase.

This use case will not extend BaseUseCase as the return type is not BaseResponse.

FindShortUrlUseCase looks like,

class FindShortUrlUseCase(private val urlRepository: UrlRepository) {    /** Executes this use case with given input. */    suspend fun invoke(input: String): String? {        return urlRepository.findOriginalUrl(input)    }}

You can see here, you don't have BaseUseCase implemented so this works as a normal class.

Now, we are done implementing all our use cases.

But one last thing is left. Think of it what is left 👻.

Correct!!! the provides and locator.

First, create a DomainProvider and DomainProviderImpl in,

base -> provider -> domain

The DomainProvider will have all the provider functions of the use cases. You have three use cases in your project so, you would have 3 functions. DomainProvider looks like,

interface DomainProvider {    fun provideCreateShortUrlUseCase(): CreateShortUrlUseCase    fun provideFindShortUrlUseCase(): FindShortUrlUseCase    fun provideFindUrlHitCountUseCase(): FindUrlHitCountUseCase}

Now, you also need needs it implementation i.e. DomainProviderImpl which looks like,

class DomainProviderImpl(private val repositoryProvider: RepositoryProvider) : DomainProvider {    override fun provideCreateShortUrlUseCase(): CreateShortUrlUseCase {        return CreateShortUrlUseCase(repositoryProvider.provideUrlRepository())    }    override fun provideFindShortUrlUseCase(): FindShortUrlUseCase {        return FindShortUrlUseCase(repositoryProvider.provideUrlRepository())    }    override fun provideFindUrlHitCountUseCase(): FindUrlHitCountUseCase {        return FindUrlHitCountUseCase(repositoryProvider.provideUrlRepository())    }}

Here, the DomainProviderImpl takes RepositoryProvider as a constructor parameter and will be responsible for passing the repositories to the use cases instances like shown above.

Lastly, only the DomainLocator is left which will be present in,

di -> DomainLocator

DomainLocator will be exposing the DomainProvider from a function but will have DomainProviderImpl in the return value.

The DomainLocator looks like,

object DomainLocator {    fun provideDomainProvider(): DomainProvider {        return DomainProviderImpl(            RepositoryLocator.provideRepositoryProvider()        )    }}

Now we have all our Locator objects setup for Database, Domain, Service, Repository, and Exception.

This is all for the domain setup and this blog.

In part -3 of the series, we will setup our routing using locations and utilize the DomainLocator to provide the specific use cases to the routes.

If you want to read more about the mongo operations check this blog.

https://himanshoe.com/mongodb-in-ktor

That is all for Part 2 of this blog. Click here for Part -3

If you like the series, do share it with people :)

Check the code here.

https://github.com/hi-manshu/ktor-url-shortener

Thank you for reading :) Hope you learned something from my experience.

If you have anything more to discuss, I will be happy to get connected at hi_man_shoe.

See you in the next blog :)

]]>

System Design: Build URL Shortening Service using Ktor (Part-1)

Himanshu Singh — Sun, 04 Jul 2021 13:28:42 GMT

Hey everybody,

While we prepare for interviews for our next Software jobs for SDE-2+ levels we generally asked questions about System Designing and one of the most common questions we come across is,

Build URL Shortening Service

In this blog series, we are going to learn,

Idea we are going to solve.
Things to take care of.
Setting up the project.
Setting up Database Layer
Moving towards building feature.
And many more.

Let us start without any delay.

Idea we are going to solve.

First, we have to discuss the idea itself. Think of this as your own personal Bit.ly which you can use to build your own URL service. But, here we need to chalk down the idea itself what we need which building this.

This will be useful even for your system design interview.

We need to build a route to take a long original URL and return a short URL.
Short URL should not be very easily predictable by the end-user.
Now, we need another route to handle the short URL which will be mapped to the original URL.
It should have an expiration time so that the short URL is inactive after a certain duration (out of scope for this blog series).

This to take care of.

To build up this solution from the ground up, we need to pre-plan for it. We need a Database service to handle the creation and mapping of the shortened URLs. We also need a definite architecture to make a robust app as well.

Our architecture will look like,

Setting Up the Project.

We will be creating the project from Intellij IDE itself using the Ktor plugin. If you want to learn more about how to create a project, check the following blog.

https://himanshoe.com/kotlin-backend-with-ktor

In this project, the plugin which we are going to use is

ContentNegotation
Gson
Status Page
Routing
Location

Now, create the packages like this. Where,

base will hold all providers, Routing, Status and Serialization
di will hold all the manual locators we have created for Domain, Database etc.
feature will have again a package of url which will contain sub-packages like repository, domain, service, etc.
util will have all your utility functions like BaseResponse, etc.
Lastly, Application will have the module extensions and the registration of the features.

Setting up database layer

In this project as well, you will use Kmongo, a kotlin wrapper over the official Mongo java client. You can read more about it here.

Implement the coroutine version of the library like,

implementation("org.litote.kmongo:kmongo-coroutine:4.2.8")

Now, create a package in,

base -> providers -> database

Here, first, create the DatabaseProvider interface and add the following functions,

interface DatabaseProvider {    val initializeName: String    val mongoClient: CoroutineClient    val database: CoroutineDatabase}

Now, create another class that will work as the implemented version of the above interface and it override. It will look like,

class DatabaseProviderImpl(private val clientName: String) : DatabaseProvider {    override val initializeName: String        get() = clientName    override val mongoClient: CoroutineClient        get() =    override val database: CoroutineDatabase        get() =}

You can see here, we are passing the clientName from the constructor because we want to follow the dependency principle of passing it from outside. Here, clientName will be used as the name for my Mongo client.

Now, let us complete the code. The final code will look like this,

class DatabaseProviderImpl(private val clientName: String) : DatabaseProvider {    override val initializeName: String        get() = clientName    override val mongoClient: CoroutineClient        get() = KMongo.createClient().coroutine    override val database: CoroutineDatabase        get() = mongoClient.getDatabase(initializeName)}

Lastly, we need provide the DatabaseProvider to other feature services we need to setup its locator in,

di -> DatabaseLocator

and it will look like,

object DatabaseLocator {    private fun provideClientName(): String {        return "ktor-url-shortner"    }    fun provideDatabaseProvider(): DatabaseProvider {        return DatabaseProviderImpl(provideClientName())    }}

Here, if you look closely we first created a client name using the provideClientName() function which you will use to instantiate the DatabaseProviderImpl class of the type DatabaseProvider.

We use the return type DatabaseProvider and not DatabaseProviderImpl because as a rule of abstraction, we don't expose the implementation of the function but only the methods/functions.

The database setup is complete.

Moving towards building feature.

As a first step, we will create a package called url in the feature module which will have sub-packages namely, domain, request, routing, service, repository, and entity.

Step 01.

First, let us create an entity inside the entity package that will be responsible for the collection structure in our database. We will name it, UrlEntity. It looks like,

data class UrlEntity(    @BsonId    val urlId: String = ObjectId().toString(),    val originalUrl: String,    val shortUrl: String,    val createdAt: String,    val urlHitCount: Int = 0)

Here,

urlId is the BsonId. Read more about it here.
originalUrl will be the long URL that we have to convert.
shortUrl is the converted URL.
createdAt is the time at which the URL was converted
urlHitCount represents the number of times we have called the short URL.

Since, you have created the entity structure, let us quickly set up the Collection in DatabaseProvider by adding,

val urlCollection: CoroutineCollection<UrlEntity>

and its implementation in DatabaseProviderImpl will look like,

override val urlCollection: CoroutineCollection<UrlEntity>        get() = database.getCollection()

Your structure of Collection is not setup using the UrlEntity that we created.

Step 02.

Now, you will setup your UrlService interface and its implementation class called UrlServiceImpl. This class will be responsible for doing all your database operations. UrlService interface looks like,

interface UrlService {    suspend fun createShortUrl(url: String): String?    suspend fun findShortUrl(url: String): String?    suspend fun findOriginalUrl(url: String): String?    suspend fun checkIfUrlIsPresent(url: String): Boolean    suspend fun getTotalCount(url: String): Int?}

Here,

createShortUrl is responsible for creating a short URL based on a given URL.
findShortUrl is responsible for getting the short URL based on a given long URL.
findOriginalUrl is responsible for getting the original URL based on a given short URL.
checkIfUrlIsPresent is responsible for checking if the original URL is present or not.
getTotalCount will return the number of times the short URL was pinged.

The UrlServiceImpl class will look like,

class UrlServiceImpl(private val urlCollection: CoroutineCollection<UrlEntity>) : UrlService {    override suspend fun createShortUrl(url: String): String? {    }    override suspend fun findShortUrl(url: String): String? {    }    override suspend fun findOriginalUrl(url: String): String? {    }    override suspend fun checkIfUrlIsPresent(url: String): Boolean {    }    override suspend fun getTotalCount(url: String): Int? {    }}

Here, you can see we are again passing the CoroutineCollection from outside via the constructor.

So, for that first, you need to create the ServiceProvider in base and ServiceLocator in di package. Your ServiceProvider looks like,

interface ServiceProvider {    fun provideUrlService(): UrlService}

and its implementation class looks like,

class ServiceProviderImpl(private val databaseLocator: DatabaseLocator) : ServiceProvider {    override fun provideUrlService(): UrlService {        return UrlServiceImpl(databaseLocator.provideDatabaseProvider().urlCollection)    }}

Here, DatabaseLocator is used to provide the urlCollection to the ServiceImpl class.

Now, let us update the ServiceLocator which will work as our DI. It will look like,

object ServiceLocator {    fun provideUrlService(): UrlService {        return provideServiceProvider().provideUrlService()    }    private fun provideServiceProvider(): ServiceProvider {        return ServiceProviderImpl(DatabaseLocator)    }}

Finally, we are done setting up the providers and the locator for UrlService.

Let us finally update the UrlServiceImpl like,

class UrlServiceImpl(private val urlCollection: CoroutineCollection<UrlEntity>) : UrlService {    override suspend fun createShortUrl(url: String): String? {        val shortUrl = generateRandomUrl()        val request = UrlEntity(            originalUrl = url,            shortUrl = shortUrl,            createdAt = Date().toInstant().toString(),        )        val isShortUrlCreated = urlCollection.insertOne(request).wasAcknowledged()        return if (isShortUrlCreated) {            shortUrl        } else {            null        }    }    override suspend fun findShortUrl(url: String): String? {        val urlEntity = urlCollection.findOne(UrlEntity::originalUrl eq url)        return urlEntity?.shortUrl    }    override suspend fun findOriginalUrl(url: String): String? {        val urlEntity = urlCollection.findOne(UrlEntity::shortUrl eq url)        updateCount(urlEntity)        return urlEntity?.originalUrl    }    override suspend fun checkIfUrlIsPresent(url: String): Boolean {        return findShortUrl(url) != null    }    override suspend fun getTotalCount(url: String): Int? {        val urlEntity = urlCollection.findOne(UrlEntity::shortUrl eq url)        return urlEntity?.urlHitCount    }    private suspend fun updateCount(urlEntity: UrlEntity?) {        urlEntity?.let { entity ->            val count = entity.urlHitCount.plus(1)            val newEntity = entity.copy(urlHitCount = count)            urlCollection.updateOne(UrlEntity::shortUrl eq entity.shortUrl, newEntity)        }    }}

Here, in the createShortUrl function you can see it has a generateRandomUrl function which is present in,

util-> Util.kt

and it looks like,

fun generateRandomUrl(length: Int = 6): String {    val allowedChars = ('A'..'Z') + ('a'..'z') + ('0'..'9')    return (1..length)        .map { allowedChars.random() }        .joinToString("")}

The above block of code will generate a random alpha-numeric string of length 6 which will represent the endpoint of the shortened URL.

Also, in the findOriginalUrl function we check if the URL is present or not. If we get the URL then we call another function there called updateCount() which is responsible for increasing the urlHitCount by 1 every time the function is called. This basically represents the number of hits the short URL has been pinged.

Rest all the functions in the UrlServiceImpl is self-explanatory as they are mere MongoDB operations. If you want to read more about the mongo operations check this blog.

https://himanshoe.com/mongodb-in-ktor

That is all for Part 1 of this blog. Click here for Part -2

If you like the series, do share it with people :)

Check the code here.

https://github.com/hi-manshu/ktor-url-shortener

Thank you for reading :) Hope you learned something from my experience.

If you have anything more to discuss, I will be happy to get connected at hi_man_shoe.

See you in the next blog :)

]]>

Using MongoDB in Ktor.

Himanshu Singh — Tue, 29 Jun 2021 21:38:13 GMT

This is the 4th blog in series of Kotlin for Backend. Do check it out if you want to get started in building backend with Kotlin using Ktor.

https://himanshoe.com/series/kotlin-for-backend

Till now, while creating an API you used collections in Kotlin to mock the database layer.

In this part, you are going to explore the database layer integration to your project. You are going to use MongoDB as your database for the project.

In this blog, you will understand,

What is MongoDB?
Integration with your project.
Initialize MongoDB in the project.
Getting hands dirty in MongoDB
Migrating your project with MongoDB

Using a database for any backend project is the core part of building a backend application.

So what are we waiting for, let us get started :)

What is MongoDB?

MongoDB is a document-based database that stores value in the form of JSON. In simpler terms, you can store data in MongoDB using plain text without taking care of Rows/Columns and structure.

Integration with your project.

Now, let us start the integration of MongoDB in your Ktor project. You can use either MongoDB's official Java library or you also have a community-driven library called KMongo. Internally, it uses MongoDB's official Java library which has Coroutines and RxJava support out of the box.

To start using it in the project, you need to add the dependency like,

implementation("org.litote.kmongo:kmongo:4.2.8")

or if you want to use Coroutines version of the library use,

implementation("org.litote.kmongo:kmongo-coroutine:4.2.8")

You will be using the Coroutine version of the library for this blog series.

There are three steps in initializing a database in any project.

DB Client -> Database -> Table/Collection

Let us learn about this in the next section.

Initialize MongoDB in the project.

Let's break it down into steps.

Step 01.

Initialization of KMongo is pretty easy. The easiest way is to use,

val client = KMongo.createClient()

This initializes the MongoDB client from the Java library and creates the instance of the client. But, in our case, you are using coroutines so you are going to initialize the coroutine version of it.

To initialize the coroutine version you can use,

val client = KMongo.createClient().coroutine

Here, coroutine is an extension function for the MongoClient.

This gets the client up and running in your project.

Step 02.

Now, since you have your client setup, you need your database to be configured as well. To configure the database in your project you can use,

val database = client.getDatabase("your_db_name")

This will create a Database with your preferred name. This database will be responsible to hold the collections used by the project.

Step 03.

Finally, you need to create a collection as well.

Collection is like a book that will store the data of a specific type.

If you remember, in the previous blog you created a User class that has id, name, and age. It looks like,

data class User(val id: Int, val name: String, val age: Int)

Here, you will create a collection for the User class like,

val col = database.getCollection<User>()

Using getCollection gets the collection for you with a specific class and returns a CoroutineCollection of User.

CoroutineCollection is a wrapper around MongoCollection in the Java driver APIs.

Now, you are done creating the Mongo client database and the User collection to store your data.

In the next section, you are going to see the basic usage of KMongo so that you can prep yourselves to refactor your code by adding the database layer.

Getting hands dirty in MongoDB

In the basic usage what you are going to do is, you are going to perform few operations in MongoDB using KMongo.

First, let's update your User class like,

data class User(    @BsonId    val id: Int,    val name: String,    val age: Int)

BSON stands for Binary JavaScript Object Notation.

Here, BsonId represents the unique id, the document will have in the ObjectId format. This will be unique identifier for your document which will be inserted.

Let us perform create operation.

You have your collection as,

val col = database.getCollection<User>()

Now, to insert/create a new document you can use,

col.insertOne(User("Himanshu", 27))

This will successfully create a User document in the collection.

But let us consider you have multiple users like in a collection and you want to insert a list of users,we can use,

col.insertMany(listOf(User("Himanshu", 27), User("John", 25)))

This is how you can create single or multiple documents using an insert query in MongoDB.

Let us perform the Read operation.

To find a single document from a collection you can use,

col.findOne(User::name eq "Himanshu")

This will return the user object.

To find a single document from a collection using id you can use,

col.findOneById("user_id")

This will return the user object.

And lastly, if you want to get all the users from the collection you can use,

val users = col.find().toList()

This will return all the users in the collection as a list of users.

Let us check an example here:

Consider you want to find all the users who are of 27 years of age in the collection. How will you find it?

Hint: Use find()

Solution:

Type 1: Inefficient solution

You can use the find method to get all the documents and then use the Kotlin find operator to get the desired result like,

val users = col.find().toList().find {                 it.age == 27            }

This is inefficient because in any case, it is first scanning the whole collection and then filtering out the data.

Type 2: Efficient solution

val list : List<User> = col.find(User::age eq 27).toList()

This will return all the users from the collection of 27years of age. eq is an operator of MongoDB which means equals.

Here, it scanned the collection to find all the documents with age == 27.

Similarly, you have methods like, updateOne(), updateOneById(), deleteOne() etc.

Migrating your project with MongoDB

As per the previous part of the series, you have the following code with multiple routes working with a list.

Not considering the location for this blog

fun Application.configureRouting() {    install(ContentNegotiation) {        gson()    }    routing {        get("/users") {            call.respond(users)        }        post("/user") {            val requestBody = call.receive<User>()            val user = requestBody.copy(id = users.size.plus(1))            users.add(user)            call.respond(user)        }        get("/user") {            val id = call.request.queryParameters["id"]            val user = users.find { it.id == id?.toInt() }            val response = user ?: "User not found"            call.respond(response)        }        delete("/user") {            val id = call.request.queryParameters["id"]            users.removeIf {                it.id == id?.toInt()            }            call.respond("User deleted")        }    }}

And here, the User class and users list looks like,

data class User(val id: Int, val name: String, val age: Int)val users = mutableListOf<User>()

As a next step, you are going to migrate from using users list to Mongo operations.

Let us break it down into steps.

Step 01.

In the application file, inside the main function, you will set up the Mongo client, DB, and collection.

  val client = KMongo.createClient().coroutine  val database = client.getDatabase("users")  val col = database.getCollection<User>()

Here, you have your client, database, and col(which is a collection).

And you will pass this collection in configure routing function as a parameter. Now, the main() function looks like,

fun main() {    val client = KMongo.createClient().coroutine    val database = client.getDatabase("users")    val col = database.getCollection<User>()    embeddedServer(Netty, port = 8080, host = "0.0.0.0") {        configureRouting(col)    }.start(wait = true)}

Now in the next step, you will use this collection.

Step 02.

Here, the updated code with the collection as parameter looks like,

fun Application.configureRouting(collection: CoroutineCollection<User>) {    install(ContentNegotiation) {        gson()    }   // your code}

Let us now update the code one by one.

Inside the routing you have the first route as,

 get("/users") {    call.respond(users) }

This returns all the users. To replicate this in Mongo you will use,

 get("/users") {    val users = collection.find().toList()    call.respond(users) }

This will now return all the users from the User collection.

Now, onto the next route. You have here,

post("/user") {        call.parameters        val requestBody = call.receive<User>()        val user = requestBody.copy(id = users.size.plus(1))        users.add(user)        call.respond(user)}

This route inserts a new user. Here, you are manually updating the id of the user. But if you can remember that we updated your User class like,

data class User(    @BsonId    val id: Int,    val name: String,    val age: Int)

Here, the annotation @BsonId will take care of the id generation in the document. So, the insert the request into the collection you will update it as,

post("/user") {    call.parameters    val requestBody = call.receive<User>()    val isSuccess = collection.insertOne(requestBody).wasAcknowledged()    call.respond(isSuccess)}

You can see, insertOne is used to insert the user in the collection. Here, we are using wasAcknowledged because if the write is successful we will return true or else false.

Similarly, for the next two routes, you can update the code with the Mongo operators like findOne and deleteOne.

This is all you need to know to get started in using MongoDB in a Ktor project.

If you like the series, do share it with people :)

Check the real implementations of Ktor with MongoDB here.

https://github.com/hi-manshu/ktor-mongodb-backend

Thank you for reading :) Hope you learned something from my experience.

If you have anything more to discuss, I will be happy to get connected at hi_man_shoe.

]]>

Understand everything about routing in Ktor

Himanshu Singh — Sun, 13 Jun 2021 16:16:05 GMT

This is the third blog in series of Kotlin for Backend. In the previous blog, we got an idea for starting and setting up a Ktor project while we built a couple of routes as well. We also saw GET, POST, and DELETE verbs of REST world as well.

Continuing to the series, we will understand all about routing in Ktor. We will understand,

Specifying routes.
Understanding route and handling requests/responses.
Creating multiple routes.
Grouping of routes.
Structuring routes.
Advanced routing using Location.
and a lot more.

Understanding routes is one of the most critical and important features of any backend technology. Let me simplify it for you.

Specifying routes

In this section, we are going to first understand what are routes and what type of routes we can create.

/user
Here, the endpoint is user
/user/{userId}
Here, the userId is the part parameter whose value can we get in the handler like call.parameters["userId"].

But the bigger question is, what are routes?

To simplify the explanation, it is like the URL we call in the browser. Let me give you a very easy example, https://google.com/search is the URL we open in the browser. Where https://google.com is the base URL and /search is the route.

Basically, routes help us differentiate requests within our code and respond to them differently. For example:https://google.com/accounts redirects us to the account page but https://google.com/search redirects us to the search page.

Understanding route and handling requests

In the /users route,

get("/users") {    // Handle request and send response }

We have a route handler where we will handle the request. We can get access to,

call.parameters: This is used to handle the path variables in the route.
call.request.queryParameters: This is used to handle the query parameters in the route.
call.receive: This is the body request with a request model.

And as a response, we have multiple options like:

call.respondText: This is used to respond user with text.
call.respondHtml: This is used to response HTMLs.
call.respond: This is used to response custom models as JSON output.
call.respondFile: This is used to response file as output.

call.respondRedirect: This is used to redirect to another route.

Creating multiple routes

In this section, we are going to understanding how we can create multiple routes in a project. Let me show you a few routes I created in the last review,

fun Application.configureRouting() {  install(ContentNegotiation) {      gson()  }  routing {      get("/users") {          call.respond(users)      }      post("/user") {          val requestBody = call.receive<User>()          val user = requestBody.copy(id = users.size.plus(1))          users.add(user)          call.respond(user)      }      get("/user") {          val id = call.request.queryParameters["id"]          val user = users.find { it.id == id?.toInt() }          val response = user ?: "User not found"          call.respond(response)      }      delete("/user") {          val id = call.request.queryParameters["id"]          users.removeIf {              it.id == id?.toInt()          }          call.respond("User deleted")      }  }}

Here, we have used GET, POST, and DELETE HTTP verbs to create routes. These are in a single file and in the same way, we can create N-number of routes. But if you see above, we are creating multiple routes with /user URL endpoint.

We are going to group them in the next section.

Grouping of Routes

In this section, we are going to group the routes in which we have /user route for GET, POST, and DELETE verbs.To group the multiple routes into one group with a specific path, we useroute extension function which looks like:

public fun Route.route(path: String, build: Route.() -> Unit): Route

Now, using the above route extension, we will update our code like:

fun Application.configureRouting() {    install(ContentNegotiation) {        gson()    }    routing {        get("/users") {            call.respond(users)        }        route("/user") {            post {                val requestBody = call.receive<User>()                val user = requestBody.copy(id = users.size.plus(1))                users.add(user)                call.respond(user)            }            get {                val id = call.request.queryParameters["id"]                val user = users.find { it.id == id?.toInt() }                val response = user ?: "User not found"                call.respond(response)            }            delete {                val id = call.request.queryParameters["id"]                users.removeIf {                    it.id == id?.toInt()                }                call.respond("User deleted")            }        }    }}

Here, you can see from the above code block, we have moved all the 3 routes with path /user inside the route extension with the same path.

This will be the same API route like:

 GET http://localhost:8080/user POST http://localhost:8080/user DELETE http://localhost:8080/user

Similarly, we can group routes into multiple nested routes like:

 route("/v1") {     route("/user") {         get {           call.respond("Hey buddy")          }     }}

This route will transform as:

 GET http://localhost:8080/v1/user

Why we need nested/grouping of routes

We need to group our routes for further development like creating versions of routes for better readability and management. For example:

http://localhost:8080/v1/userhttp://localhost:8080/v2/userhttp://localhost:8080/v3/user

Structuring of routes

Now, if you see the above code we have defined 4 routes. But it will become a mess if we start adding routes let's say 100 or even 200.

Here, in this section, we are going to learn how we can create a proper structure to manage routes in the project.

The code we have is:

fun Application.configureRouting() {    install(ContentNegotiation) {        gson()    }    routing {        get("/users") {            call.respond(users)        }        post("/user") {            val requestBody = call.receive<User>()            val user = requestBody.copy(id = users.size.plus(1))            users.add(user)            call.respond(user)        }        get("/user") {            val id = call.request.queryParameters["id"]            val user = users.find { it.id == id?.toInt() }            val response = user ?: "User not found"            call.respond(response)        }        delete("/user") {            val id = call.request.queryParameters["id"]            users.removeIf {                it.id == id?.toInt()            }            call.respond("User deleted")        }    }}

Here, what we can do is we can segregate the routes in individual route extension functions to do their work like:

 fun Application.configureRouting() {    install(ContentNegotiation) {        gson()    }    routing {        getAllUsers()        createUser()        getIndividualUser()        deleteUser()    }}

You can see that, now the routes are converted to functions that are nothing but just extensions to routes. Now the above functions look like this:

fun Routing.createUser() {    post("/user") {        val requestBody = call.receive<User>()        val user = requestBody.copy(id = users.size.plus(1))        users.add(user)        call.respond(user)    }}fun Routing.getAllUsers() {    get("/users") {        call.respond(users)    }}fun Routing.getIndividualUser() {    get("/user") {        val id = call.request.queryParameters["id"]        val user = users.find { it.id == id?.toInt() }        val response = user ?: "User not found"        call.respond(response)    }}fun Routing.deleteUser() {    delete("/user") {        val id = call.request.queryParameters["id"]        users.removeIf {            it.id == id?.toInt()        }        call.respond("User deleted")    }}

This is one of the ways to structure routes. In the real-world application, we will have multiple routes and we need a proper way to define them. Now, I will show my recommended way to structure routes in the application with an example.

Let's say we have features related to User, Post, and Comments in our application. So, we would have routes individually for them as well.

What I would do is, I will create a package called features. Inside that, I will have user, post, and comment packages. These packages have their own routes.

I will create a file called, UserRoute, CommentRoute, and PostRoute, and the code will look like this:

// Routes in UserRoute.kt filefun Application.userRoutes() {    routing {     // the user routes    }}// Routes in PostRoute.kt filefun Application.postsRoute() {    routing {      // the post routes    }}// Routes in CommentRoute.kt filefun Application.commentRoutes() {    routing {      // the comment routes    }}

So, here you will add the routes here for the required features which you might need for your application.

Since these are the Routes we created for individual features, we need to register them in configureRouting() function like:

fun Application.configureRouting() {    install(ContentNegotiation) {        gson()    }    routing {        userRoutes()        postsRoute()        commentRoutes()    }}

This is how I will segregate routes of the application based on the features I have. And, this is called packaging by feature.

Advanced routing using Location.

Location is a typed version of creating routes. This is used to manage URLs and parameters. No matter if it's for a path variable or query parameters.

To install Location, first, we need to add the dependency:

implementation("io.ktor:ktor-locations:$ktor_version")

and we also need to install it in the main() function in the Application class::

fun Application.main() {    install(Locations)}

Let's take a pause here and understand what is Location and how it represents routes in Ktor?As I mentioned, Location is a representation of routes in a typed way which we have to use by class containing parameters required by the URL.

A very basic example of Location is:

get<Users> {     call.respond(users)}

Here, the GET is not taking a URL but a class that looks like this:

@Location("/users")class Users

The above code is making sure that we don't write /users in the GET route rather we use the typed way.

Let's talk about migrating the existing routes to Location. The current code is:

fun Application.configureRouting() {    install(ContentNegotiation) {        gson()    }    routing {        get("/users") {            call.respond(users)        }        post("/user") {            val requestBody = call.receive<User>()            val user = requestBody.copy(id = users.size.plus(1))            users.add(user)            call.respond(user)        }        get("/user") {            val id = call.request.queryParameters["id"]            val user = users.find { it.id == id?.toInt() }            val response = user ?: "User not found"            call.respond(response)        }        delete("/user") {            val id = call.request.queryParameters["id"]            users.removeIf {                it.id == id?.toInt()            }            call.respond("User deleted")        }    }}

Let us break this down into steps:

Creating Location class.
Migrating routes to the classes.

Creating Location Class

We will create a Location class called UserLocation. This will handle all the routes /users and /user.

Migrating routes to the classes.

Let's migrate the first route, i.e. /users to the Location feature.

For that, I will create a class called Users like:

@Location("/users")class Users

Here, Location annotation takes the route, which is /users in our case. This will be used to configure the routing in the project.

Now, let's convert the following code:

get("/users") {    call.respond(users)}

This is how it looks with Location:

get<Users> {     call.respond(users)}

Here, the Users class is the Location that handles the /users.

Now, let's see how we can handle parameters in Location.

For this, we are going to refactor the following route:

get("/user") {      val id = call.request.queryParameters["id"]      val user = users.find { it.id == id?.toInt() }      val response = user ?: "User not found"      call.respond(response)}

Then, we are going to create a Location for /user:

@Location("/user")data class FindUser(val userId: String)

Here, in the FindUser class, we have userId as a parameter, which we will get as a query parameter.

Now, the updated code becomes like this:

get<FindUser> { request ->     val id = request.userId     val user = users.find { it.id == id.toInt() }     val response = user ?: "User not found"     call.respond(response)}

Here, we are getting the request param inside the handler and using that we can get the userId.

Similarly, we can create a Location for URL which has a path variable like:/user/{userId}

Here, userId is in the path. For that Location looks like this:

@Location("/user/{userId}")data class FindUserById(val userId: String)

If you look closely, FindUser and FindUserById look the same. Where in one case, userId is a query parameter, and in others its the path variable

This is the best way to handle the route if you want to handle it in a typed way.

This is all you need to know for routing in Ktor to start implementing in your project.

If you want to check real implementations of Ktor with the MongoDB project. Click here.

https://github.com/hi-manshu/ktor-mongodb-backend

Thank you for reading :)Hope you learned something from my experience.

If you have anything more to discuss, I will be happy to get connected at hi_man_shoe.

See you in the next blog of the series.

]]>

Kotlin backend with Ktor : 101

Himanshu Singh — Thu, 10 Jun 2021 18:44:18 GMT

This is the second part of the series, Kotlin for backend. If you have not checked out the first part click here.

Since we understand that we can use Kotlin to build scalable backend apps. Let us move to the next step. We need to decide the framework we are going to use.

From the title, you might have known the answer to this, but let me still mention that we are going to use Ktor Framework by Jetbrains itself to build our backend services.

We also have different options like Vertx, Micronauts, etc I chose to go with Ktor because:

It is built by Jetbrains, the same firm which has given us Kotlin.
It is very lightweight.
It supports Coroutines by default which helps the app to scale and it also supports all the features of Kotlin like DSLs.

In this blog, we are going to learn and understand the basics of API development using Kotlin and Ktor. We are going to divide the blog in:

Setting up the project
Running the starter project.
Building our own APIs.
and much more.

So, before any further due, let's start.

Setting up the project.

We can start setting up the project in two ways either follow this link Ktor Startup project generator or install the Ktor plugin in your Intellij IDE to start setting up your project. I will be following the Plugin way to create my project. Let's start,First I will create a new project using New project

Now, after going to next you will see the following screen:

Here, first, we select Ktor from the left panel and we can only see this option if we have installed the Ktor Plugin mentioned above.

Once we have selected Ktor as an option, we need to fill up few details, like:

Name: It is used to define the name for the project
Location: It is used to specify the path in the local PC/Mac where we want to store the project.
Build System: It means the build system responsible to build the project. In our case, we will use Gradle Kotlin.
Website: This is the website we will use to generate project Artifact.
Artifact: This is only read-only generated via the Website you entered.
Ktor Version: This is used to specify the version we will use for Ktor. In our case, we will use 1.6.0, the latest version.
Engine: This is one of the most important parts of creating the project. This will be used to run the server. We will select Netty
Configuration in: This is used to say, that where do we need to store server variables.
Add Sample code: This will be used to add some dummy code to the project.

Now, after specifying all the things required for creating the project we press next.

In the above screen, we will select the features we need to finish the setup of the project.

For now, we will select Routing and click Finish to go to the project.

Note: We can also add other plugins later as per the need for our project. We are going to see a lot of them in coming blogs.

We have successfully created our project.

Running the starter project.

In the above image, you will see inside the src folder we have main and test folders. The main folder will contain all the code for the project and the test folder will have the test for your code.

Now, let's run the project and see the output. You can run the project by click run on IntelliJ.You will see the following as output:

And, when you open the URL, you will see "Hello World" as output like this:

So, this is the default route we will handle in the project.

Let's discuss the routing.

Routing is the plugin that we selected and is always installed by default. This is responsible for handling all the routes we will build for our project.

Initially, when you opened https://0.0.0.0:8080, it triggered the / route which displayed the Hello world result in the browser.

The routing is present inside, plugins -> Routing and it looks like:

fun Application.configureRouting() {    routing {        get("/") {            call.respondText("Hello World!")        }    }}

If you can see, here, we are using the extension function property and attaching configureRouting to the application. Inside that, we call the routing function and that handles the route.

Here, you can see, we are using GET to build a route to match a GET Request with an empty path.

And to register all the routes in the application we navigate to the Application file and inside the main function will pass configureRouting like:

fun main() {    embeddedServer(Netty, port = 8080, host = "0.0.0.0") {        configureRouting()    }.start(wait = true)}

Since configureRouting is an extension function of the Application we can directly call configureRouting here directly.

Building our own APIs.

In this section, we are going to see how we can build our own custom routes.We will build a custom Users route where we will build a couple of routes. They are:

GET all Users
GET an individual User
DELETE User
Create a User using POST.

First, we will create a model for the User which will have an ID, Name, and Age.

data class User(val id: Int, val name: String, val age: Int)

In this case, we won't be using a Database. To simulate the database in our project we will use a list(MutableList) type structure which will be responsible for adding/deleting users.

So, let me create a mutable list of user like:

val users = mutableListOf<User>()

Now, just to test let's update our default GET call like:

 get("/") {     call.respond(users) }

And if you run this, you will get an error,

Response pipeline couldn't transform '*class java.util.ArrayList*' to the OutgoingContent

The reason is that the project can't serialize the list as Output.

Now, let's fix it.

To fix it we need to install Content Negotiation. To do this we will go to our Routing file and install it like:

 install(ContentNegotiation) {   gson() }

To install Gson in the project, we will add its dependency in the Gradle file like:

    implementation("io.ktor:ktor-gson:$ktor_version")

Here, Content Negotiation will use Gson for Serializing/deserializing the content in the specific format.

And, finally, if you run the project and open http://0.0.0.0:8080/ you will see the following output.

Creating a User

In this section, we will see how we can create a user by adding the User JSON in the body of the request.

First, we will create a user route with POST request like:

 post("/user") { }

Now, as a next step, we will have to accept a body from a user. In Ktor, we use receive to take the request like:

 post("/user") {    val requestBody = call.receive<User>() }

Now, the requestBody will be mapped to the User object and it will contain the JSON. We also need to add an ID to it.

What we would do here is, we will add the (index+1) as the ID every time we add an object to the list like:

 post("/user") {            val requestBody = call.receive<User>()            val user = requestBody.copy(id = users.size.plus(1))            users.add(user)  }

And, at last, we will respond the added user as a response. Finally, the route looks like this:

post("/user") {            val requestBody = call.receive<User>()            val user = requestBody.copy(id = users.size.plus(1))            users.add(user)            call.respond(user) }

Let's see this in action. We will first run the app and let us, open postman. We will fire up a request with User JSON and the response will also look like this:

Here, we passed on the request in the body and we got the response after adding it to the users list.

And finally, we will update the GET route to:

 get("/users") {   call.respond(users) }

Get a specific User

In this section, we will get a specific user from the list by its id. It will be a GET request.

First, we need to create the route. We will name it as /user as well which will take id as a query parameter.

get("/user") {}

In this block, we will get the id from the query like:

get("/user") {            val id = call.request.queryParameters["id"] }

Now, we need to find the user from the user list matching the id. For this, we will use the find operator present in Kotlin like:

get("/user") {            val id = call.request.queryParameters["id"]            val user = users.find { it.id == id?.toInt() } }

Lastly, if the user is null, that means the user is not present and if it's not null we get the specific user. Let's convert that into code.

get("/user") {            val id = call.request.queryParameters["id"]            val user = users.find { it.id == id?.toInt() }            val response = user ?: "User not found"            call.respond(response)}

For this to work, when you re-run the project, first you need to add a user and then find the user with an id.

Deleting a User.

In this section, we are going to delete a user if the provided userId is present. It will be pretty similar to what we did in getting user by id. The only change we are going to do is we need to replace GET to DELETE.

delete("/user") {            val id = call.request.queryParameters["id"]}

Now, we will just remove the user from the list if the user is present.

We will update the code like:

 delete("/user") {            val id = call.request.queryParameters["id"]            users.removeIf {                it.id == id?.toInt()            }            call.respond("User deleted")}

This will delete the user.

We have finally created all the routes we wanted to do at the start of the blog. This is the basic example to get started with creating routes in Ktor.

Finally, the code in my route looks like this:

data class User(val id: Int, val name: String, val age: Int)val users = mutableListOf<User>()fun Application.configureRouting() {    install(ContentNegotiation) {        gson()    }    routing {        get("/users") {            call.respond(users)        }        post("/user") {            val requestBody = call.receive<User>()            val user = requestBody.copy(id = users.size.plus(1))            users.add(user)            call.respond(user)        }        get("/user") {            val id = call.request.queryParameters["id"]            val user = users.find { it.id == id?.toInt() }            val response = user ?: "User not found"            call.respond(response)        }        delete("/user") {            val id = call.request.queryParameters["id"]            users.removeIf {                it.id == id?.toInt()            }            call.respond("User deleted")        }    }}

Summary

This is a very beginner-friendly starting point to get started to build your routes in Ktor. Go ahead and build your own.In the upcoming blogs, we will see advanced routing and diving deeper into understanding routes in Ktor. We will also see the grouping of routes in Ktor as well.

Say hi @hi_man_shoe

]]>

Kotlin for Backend.

Himanshu Singh — Mon, 07 Jun 2021 22:43:33 GMT

We have a lot of code experience to share as an Android developer using Kotlin or a Backend developer using Java.

When we talk about backend technologies, we have a lot of languages/frameworks like Go, Java, Python, etc. But when we talk about Kotlin as a backend language, it might raise a lot of eyebrows 🤨.

In this blog, I am going to discuss the what and why you should choose Kotlin as your next programming language.

We can break this blog into:

What is Kotlin & can we really use it in the backend?
Why you should consider Kotlin as your next backend language?

So, before any further due, let's start.

What is Kotlin?

As we all might be familiar with Kotlin as a first choice language for the Android app development world. It has been a go-to language for most devs around the globe for app development.

With Kotlin gaining enormous popularity, it was extended to build cross-platform apps for platforms like iOS, Web, and even Desktop. Yup, you read it right!!! and, I know what will be your next query now.

Can we really use it in the backend?

Ok, now the billion-dollar question? Can we use Kotlin for Backend? Or is Kotlin production ready?

The short answer is, Yes and absolutely Yes.

Why you should consider Kotlin as your next backend language?

Now, I am sure you would be asking this question as to yourself that why you should consider Kotlin in our backend ecosystem. For that, let me help you with this:

Amazing features: Kotlin has a lot of amazing features to offer out of the box( like Null Safety, Lazy initializations, etc)
Good community support: Since it's widely accepted by developers across the globe, it has a good community presence.
Good tooling support: It is built by Jetbrains the brains behind IDE's like Android Studio, trust me, you will find one of the best tooling support.
With the help of Coroutines, it helps to write asynchronous or non-blocking code.
Framework support for Kotlin: We have a lot of frameworks to build robust, scalable apps like Ktor, Vertx, etc.
If you have an existing Java project, Kotlin is interoperable with any java framework like Springboot.

Summary

In my opinion, if you are an Android developer or someone who is going to start learning to build backend apps, you should definitely consider trying Kotlin as a backend language.

PS: Kotlin has an easy learning curve as well :)

Say hi @hi_man_shoe

]]>