include::migration/4.x.adoc[]
include::migration/3.x.adoc[]

=== Upgrading from 1.x to 2.x

You will find here notes/tips about how to migrate from 1.x to 2.x.

==== Maven coordinates
`org.jooby` became `io.jooby`. Hence, use `<groupId>org.jooby</groupId>` for all dependencies.

==== Modules
|===
|1.x|2.x
|jooby-apitool| no real equivalent, use a combination of https://jooby.io/modules/openapi/[jooby-maven-plugin] and https://jooby.io/modules/openapi/#openapi-swagger-ui[jooby-swagger-ui]
|jooby-hbv| n/a
|jooby-lang-kotlin| not needed anymore, part of core now
|jooby-servlet| n/a
|===

==== API

API still similar/equivalent in 2.x. Except for the one listed below:

.Classes
|===
|1.x|2.x
|org.jooby.Module| io.jooby.Extension
|org.jooby.Env| io.jooby.Environment
|org.jooby.Mutant| io.jooby.Value
|org.jooby.Render| io.jooby.MessageEncoder
|org.jooby.Parser| io.jooby.MessageDecoder
|org.jooby.Err| io.jooby.StatusCodeException
|org.jooby.Results| - (removed)
|org.jooby.Result | - (removed)
|===

==== Route Pipeline

The concept of route pipeline still applies for 2.x but works different.

In 1.x there is no difference between handler and filter (including before and after). The way to
chain multiple handler/filter was like:

.Pipeline in 1.x
[source, java]
----
{
  use("*", (req, rsp, chain) -> {
    System.out.println("first");
    // Moves execution to next handler: second
    chain.next(req, rsp);
  });
  
  use("*", (req, rsp, chain) -> {
    System.out.println("second");
    // Moves execution to next handler: third
    chain.next(req, rsp);
  });
  
  get("/handler", req -> {
    return "third";
  });
}
----

A filter in 1.x requires a path pattern, here we use a wide matcher `*` for `first` and `second` filters.
Both of this filters are going to be executed before the real `handler`.

.Pipeline in 2.x
[source, java]
----
{
   use(next -> ctx -> {
     System.out.println("first");
     // Moves execution to next handler: second
     return next.apply(ctx);
   });
   
   use(next -> ctx -> {
     System.out.println("second");
     // Moves execution to next handler: third
     return next.apply(ctx);
   });
   
   get("/handler", ctx -> {
     return "third";
   });
}
----

Execution is identical to 1.x. The `first` and `second` decorators are executed before the handler.
Differences with 1.x are:

- javadoc:Route.Decorator[] doesn't support a path pattern. In 1.x the path pattern is required for a filter.
- Only the handler supports a path pattern and HTTP-method.
- A handler might have zero or more decorator.
- In 2.x we chain all the decorator defined before the handler.

The routing matching algorithm in 2.x is more efficient and fast, because:

- Matches a single path pattern (due decorator lacks of path pattern)
- Uses a radix tree, not regular expression like in 1.x
- It never executes a decorator if there isn't a matching handler

More detailed explanation of route pipeline is available in the <<core-router-pipeline, router pipeline documentation>>.
