OSLC to newcomers

#1

I’ve been trying to get into OSLC for DOORS customization for about more than a month now. I don’t know if it’s just me but there seems to be no tutorial for beginners. Sure the official website has guides on semantics and everything but newcomers like me face problems in implementing/experimenting with the technology.

For example, I’m stuck at setting up the eclipse/lyo environment. I was able to import the oslc4j SDK from github, and that’s where I ran into my primary problems-

  1. The import wasn’t smooth and nobody discusses these errors anywhere on the internet (or maybe I’m just bad at googling)
  2. What do I do with the SDK? How to use it? How to begin with a hello world REST client?

I’ve worked on PLM tools previously and I have decent programming knowledge, and I believe I can pick things up on that aspect. But OSLC is completely open source and many people describe their own implementations. They’re all very different.

I apologize if it’s a long post but I’ve spent quite a few weeks understanding just bits and pieces of OSLC with no clear understanding of how to implement it using eclipse/lyo. If any of you can guide me in the right direction, I would greatly appreciate it!

#2

Hello John,

I am sorry for your steep learning curve with OSLC and Eclipse Lyo. Most of the problems arise from these reasons:

  1. Widely avaible guides were written many years ago and discrepancies have since crept in.
  2. Most guides assume you have solid Java and Maven skills as well experience with REST APIs in general.
  3. Some topics are not covered well :man_shrugging:
  4. Many existing apps with OSLC interfaces were developed before the standards were fully finalised.

We have tried to address #1 with having https://oslc.github.io/developing-oslc-applications/ as the only source of hands-on OSLC development guides that we keep relatively up-to-date. There is little we can do with #2 at the time. We need help from people like you with item #3 by contributing content to https://github.com/OSLC/developing-oslc-applications or at least filing bugs to indicate where our guides fall short. You are definitely not bad at Googling, the OSLC community is quite small and the initial learning curve can seem a bit steep. #4 means that different servers can have small gotchas to interface them properly. We don’t have a list of such gotchas but would be happy if you help us start one.

  1. You should not need to import any code from Github unless you want to help us develop the SDK, you should be able to simply include Lyo libraries in your Maven or Gradle project.
  2. If you are trying to develop an OSLC Server, I strongly suggest to take a look at Lyo Designer.
  3. Did you already go through https://oslc.github.io/developing-oslc-applications/eclipse_lyo/setup-an-oslc-provider-consumer-application.html?
  4. If you are trying to develop an OSLC Client towards DOORS, you should be aware most guides will work with Lyo Client 2.4.0, but a new version 4.0.0 is in the works and will be incompatible in some ways. Stick to 2.4.0 for the time being (NB! The code you found on the master branch is an unfinished 4.0.0 codebase). See https://github.com/OSLC/lyo-samples/blob/master/README.md for sample code.

Cheers,
Andrew

#3

Links to some “hello world” REST clients:

#4

Hello @andrew, thank you very much for a quick and detailed reply!

You’re absolutely right. Almost all of the guides assume that I have solid Java and Maven skills. Prior to my interest in OSLC I’d never even heard of Maven, so I’m a beginner to that as well.
Once I am confident in my OSLC related skills, I will definitely contribute whatever I can to the OSLC community. I would definitely not want newcomers to feel overwhelmed like me.

Addressing your point number 3, that was the first tutorial I went through. I did what was exactly mentioned and yet I had a lot of errors. I was able to resolve some of them by reconfiguring build paths etc, but some core concept related issues are yet to be unresolved. I am attaching an image file that shows the error (Status: not available).

Screenshot (38)
Screenshot (38)1366×768 91.2 KB

Googling the error showed me that some other people had the same issues, but their fixes don’t work for me.

I shall definitely check out all the links you’ve posted here and try them out myself. Thank you!

#5

@sonofel, this error is due to you not hitting the registered URL under the context. A context in Maven/Jetty is configured like this: https://github.com/OSLC/lyo-adaptor-sample-modelling/blob/master/adaptor-rm-webapp/pom.xml#L102. You can also use an “emtpy” context <contextPath>/</contextPath> but that may cause some extra issues. The “registered URL” needs to be:

  1. Mapped to a servlet.
  2. The configured JAX-RS Application class shall register all the JAX-RS Services (Resources).
  3. Those registered classes shall have the necessary annotations (JAX-RS and Lyo) on the class and method (handler) level.

If you have limited Maven exposure, maybe try to clone https://github.com/OSLC/lyo-adaptor-sample-modelling/tree/master/adaptor-rm-webapp and start this web app and see if it works for you. If it does, just go ahead modifying code for your needs.

There is naïve client inside for retrieving an OSLC Service Provider Catalog of another OSLC Server. Most OSLC Servers have an SPC (see this for more info), which you should always start from when exploring (and for IBM tools, it’s usually a Jazz RootServices document before you can access resources that require auth; we have a tutorial here on how to make one but you only need it if you want to add your server as a Jazz OSLC Friend).

For now you can ignore the fact all that code was generated, but later you may want to install Lyo Designer and explore the model (project in an adjacent folder in the repo). Good luck!

1 Like
#6

With compiler errors, you should not run the application.

Maven is hard even for users used to Java. There are some behaviors that seem to be totally random in Maven with Eclipse and web development. I often see compiler errors that go away when running Eclipse Project clean and then Maven clean. I had to delete my maven repository folder several times. It is absolutely crucial to have a JDK set up in Eclipse…

I summarized some of my experiences and learning with Lyo 2.4 and Doors next here: https://jazz.net/library/article/92596 . This also has some hints on the Maven part that originate in the Lyo 2.4 documentation. The article explains a bunch of things I ran into and had to learn when starting with Lyo. So maybe there are some hints for you as well. More related information from my blog: https://rsjazz.wordpress.com/2019/03/07/type-system-manager-part-2/ .

Good luck!

1 Like
#7

@sonofel! I hope you’re not getting overwhelmed with responses trying to help. But I suspect many are feeling your pain, because (at least) I have been there as well.

Using Eclipse with Maven projects is indeed confusing for beginners. You can spend a lot of time solving problems that don’t really exist. If you’re ever suspicious of compile errors, first thing is to do Alt+F5 (Right-click the project, and select Maven > Update Project). This updates Eclipse’s IDE with the real compile situation as define in your maven pom.xml file. pom.xml is what counts in the end.

In case you are working to develop a client, I can also give you a pointer to a recent client code that works with the latest Lyo 4.0.0-SNAPSHOT. namely, client-oauth-discovery-dui.
It is recently developed, so it should be more stable. I have not used it against Jazz-based systems, but other similar platforms.

Finally, if you’re considering using Lyo Designer, worth mentioning that the latest version automatically generates the maven-related files for you. This basically means you don’t need to do any of the steps under OSLC Server/Client Setup

I have not had the time to document these steps, but if of interest I can give you quick pointers.

1 Like
#8

Hello @rsjazz,

Your link looks like it could help me a lot with the http services. I am still not clear on how to use the oslc4j APIs for http services, so I think your article would help me out in that area.
Thank you very much!

#9

Hello @jad,

It sure is hopeful to know that most of you are quite comfortable with OSLC now, after going through a tough beginner’s phase, in which I currently am.

You’re absolutely right! Either cleaning or updating my project seems to solve most of the Maven issues.
I shall definitely check out your code. I’m positive that it’ll help me understand some of the important basics.

I don’t think I’ll be using Lyo Designer, at least for now. However, if I need to use it in the future, I shall keep this in mind.

Thank you very much!

#10

Good luck @sonofel.
Don’t hestitate to contact us if you face specific issues with the code.

2 Likes
#11

Thank you, @jad.
I’ll keep that in mind; the community here sure is nice and helpful!

1 Like