Skip to content

Lyo 5.0 migration notes

Jump to bottom
Andrew Berezovskyi edited this page May 10, 2022 · 21 revisions

Migration of the codebase

How should I upgrade from Lyo 4.0.0 or 4.1.0?

  1. Switch Lyo to 5.0.0.beta1 if everything work, bingo! Otherwise, read on.
  2. Switch Lyo to 5.0.0.alpha1. This release drop JDK 8 support, removes server/wink and server/registry components.
    1. If you code fails to build due to missing Lyo artifacts, most likely you were using the "old old" Wink-based client. Migrate to the new Lyo client introduced in Lyo 4.0.
    2. If your build fails for any other reason, or succeeds but fails to run correctly, it's JDK upgrade.
  3. Switch Lyo to 5.0.0.alpha2.
    1. If you code fails to build due to missing Lyo artifacts, it's because you were using the old Wink-based client. Migrate to the new Lyo client introduced in Lyo 4.0.
    2. If your build fails for any other reason, or succeeds but fails to run correctly, it's the Jena 4.0 upgrade. See the Git history of the Lyo project to see what changes we had to do throughout our codebase to run with Jena 4.0 code.
  4. Switch Lyo to 5.0.0.alpha3.
    1. If your code fails, most likely it's because of the Jersey upgrade from 2.25 to 2.35.
    2. We also upgraded Jena from 4.0.0 to 4.2.0 but no breakage is expected there.
  5. Switch Lyo to 5.0.0.alpha4
    1. If your code fails, it's most likely due to the SPARQL-related changes in Jena 4.3.
  6. Make sure the release candidate is 5.0.0.CR and the final release is 5.0.0.Final. This way OSGi and Maven IDs will be 100% unified.

How should I upgrade from Lyo 2.4.0?

Migrate to the new Lyo Client and then follow the 4.x->5.0 migration guide above.

You can also delete Eclipse Maven repositories from you POM files because Lyo is on Maven Central since 4.0.

How should I upgrade from Lyo 2.2.0?

You need to make 2 major upgrades:

  • From Jena 2.x (aka HP Labs Jena) to Jena 4.x, and
  • From JAX-RS 1.1 to JAX-RS 2.0 (and from Wink to another JAX-RS framework because Wink was EOLed and put in Apache Attic ca. 2015).

How should I upgrade from Lyo 2.1.2?

Make sure you have migrated to JDK 8 and continue with the steps for Lyo 2.2.0 upgrade.

How should I upgrade from 1.x, 2.0.0, or 3.0.0-SNAPSHOT?

Upgrade from JDK 7 to JDK 8 and switch Lyo version to 2.1.2 (except for the dependencies in the lyo.server group, such as oauth-webapp; keep them at 2.1.0). Then continue with the steps for Lyo 2.2.0 upgrade.

Common questions

Why did Lyo drop Jena 3.x support?

Becase Jena published an RDF/XML related CVE was published for Jena that we deem quite relevant for Lyo users. Andrew from Eclipse Lyo engaged with Jena developers to help backporting the CVE patch from 4.x to 3.17.0 to produce 3.17.1 but Jena developers decided that they don't have time to focus on maintaining two branches of Jena.

Why did Lyo drop JDK 8?

Because Jena dropped JDK 8 support. They did this for 2 reasons mainly:

  1. Use the new JSON-LD library that adds JSON-LD 1.1 support, which is written from scratch in Java 11.
  2. Switch from Apache HttpClient to the new java.net.HTTP client. Lyo 5.x does not change the underlying implementation in the Lyo client compared to 4.x. We still rely on the JAX-RS 2.0 client interface and in most cases it will use Apache HttpClient 4.x behind the scenes.

Why did Lyo update Jersey?

  • Because the old Jersey has a CVE (XML-related, which may impact RDF/XML processing in Lyo).
  • Because the old Swagger/OpenAPI libraries have a CVE and the fix is in the version that is incompatible with the old version of Jersey.

Why should I upgrade to the new versions of Lyo?

  1. Lyo 5.0 addresses ⚠️ CVE-2021-41042 as well as CVEs in Jena (RDF/XML-related) and Jersey.
  2. Lyo 4.1 added oslc-ui library for easier support of OSLC Delegated UIs.
  3. Lyo 4.0 allows you to migrate from Apache Wink to any JAX-RS 2.0 compatible framework, e.g. Jersey 2.x. Wink is abandoned since 2015. There was no Lyo 3.0 release because of (a) abandoning a 3.0.0-SNAPSHOT "branch" and (b) to avoid confusion with OSLC 3 spec effort.
  4. Lyo 2.4 added JSON-LD support for content negotiation.
  5. Lyo 2.3 added Lyo Validation that supports OSLC Constraints (Shapes) and SHACL Shapes.
  6. Lyo 2.2 added Lyo Store, an Object-Graph Mapper allowing you to easily persist Lyo POJOs in a SPARQL-accessible triplestore. It also includes most features added in 3.0.0-SNAPSHOT except anything that would break OSLC 2 compatibility (back in the day when OSLC 3 spec draft had incompatible changes, OSLC 3.0 OASIS Standard is backwards compatible with OSLC 2).
  7. Lyo 2.1.2 was the first stable build produced by the new Lyo leadership in 2016 after the project was mostly dormant since 2013. It also includes conservative bugfixes from 3.0.0-SNAPSHOT.

Do you support Tomcat 10 and/or Jakarta EE?

No, Tomcat 10 removes support for JavaEE / JakartaEE 8 and JAX-RS 2.0 and adds support for JakartaEE 9 and JAX-RS 3.0. Ubuntu 22.04 LTS does not seem to pick Tomcat 10 up in the default repositories and we will keep releasing JavaEE based libraries until JakartaEE 9+ support becomes necessary (which will most likely be coupled to the Jersey 3.x migration when 2.x becomes EOL).

Also see JavaEE / JakartaEE support table for Eclipse Jetty.

Can you make releases to the old versions of Lyo?

In theory, yes (but not for Lyo Designer). I am quite against feature releases but bugfixes/CVEs should be perfectly fine for new patch releases. Since 4.0.0, Lyo is developed in a single repo (monorepo) and it will be easier to make them. For 2.x, a new branch without an "ancestor" will need to be created (with the --orphan flag) and the monorepo structure and build configs will need to be updated to match 5.x, but it's doable (we are NOT going to un-archive the old repos as per agreement with Eclipse).

Potential candidate branches:

  • maint-4.1 for JDK 8 / Jena 3 / JAX-RS 2.0 users.
  • maint-2.4 for JDK 8 / Jena 3 / JAX-RS 1.1 users.
  • maint-2.2 for JDK 8 / Jena 2 / JAX-RS 1.1 users.
  • maint-2.1 for JDK 7 / Jena 2 / JAX-RS 1.1 users

For those releases to happen, there needs to be:

  1. Enough demand.
  2. Someone providing patches (or funding to someone who will produce the patches). One example is Wink, seems like IBM forked Wink 1.1 and provides security updates for it to this day. If they are happy to open-source the Wink patches they made, we may consider another 2.x patch release

This is because release engineering work would take a long time and will distract us from Lyo 5.x development, so there should be a good reason for that.

Clone this wiki locally