AsyncAPI Feedback

[JEFFLUFC]

This issue is provided as a thread that may be added to with any thoughts/comments/questions on our work on the Java Template.

[derberg]

Hey, my first question is about below check that you have in the index

  if (!asyncapi.hasComponents()) {
    return null;
  }

why do you quite when components are not there? components are optional, for reusability only, the same data can be directly available under channels

[derberg]

Important for templates that land in AsyncAPI organization is to make sure they are vendor-neutral. It is ok to support some specific vendor, but there should be an option to use another vendor or some non-vendor-related tool.

Now readme says This template generates a Java application using Java Messaging Services (JMS) with the IBM MQ bindings.

So it sounds like only IBM MQ is supported. So either readme requires an update or maybe you can add another tutorial where you showcase the code template on some different tool, other than IBM.

My hint, although I'm not a hackathon judge, is that you need to make it as clear as possible, especially in submission, so the judge doesn't disqualify you right away for the non-vendor-neutral approach. Like some banner or whatever information with link to the document/video that shows template using stuff different than IBM

[derberg]

Please specify in config https://github.com/ibm-messaging/mq-asyncapi-java-template/blob/main/package.json#L57 what protocols are supported by the template

[JEFFLUFC]

Important for templates that land in AsyncAPI organization is to make sure they are vendor-neutral. It is ok to support some specific vendor, but there should be an option to use another vendor or some non-vendor-related tool.

Now readme says This template generates a Java application using Java Messaging Services (JMS) with the IBM MQ bindings.

So it sounds like only IBM MQ is supported. So either readme requires an update or maybe you can add another tutorial where you showcase the code template on some different tool, other than IBM.

My hint, although I'm not a hackathon judge, is that you need to make it as clear as possible, especially in submission, so the judge doesn't disqualify you right away for the non-vendor-neutral approach. Like some banner or whatever information with link to the document/video that shows template using stuff different than IBM

@derberg We have addressed the wording in the readme in this PR https://github.com/ibm-messaging/mq-asyncapi-java-template/pull/9

[derberg]

We have addressed the wording in the readme in this PR

Make sure other parts are also clear about it. For example, readme still claims that only ibmmq protocol is supported. I also advised you to put it as clear info in the config. So provide list of other protocols.

[rcoppen]

@derberg I'm not sure how to address the 'supported protocols' to make it more generic. ibmmq is the example but the template generator shows the way for other jms providers to add an example. However, as a general point jms is an api and not a protocol.

My view is that the jms code is generic and any jms provider code use that if they compiled with their vendor specific jars. As such, I think we can reasonably claim ibmmq and jms protocol support (jms is a legitimate AsyncAPI binding) and in the doc we make it clear that the maven build step is extensible for another jms provider to come along and modify as appropriate. What are your thoughts?

[derberg]

@rcoppen I'm a noob in relation to the discussion about jms 😄 - is it API or a protocol, this is something to talk about in places like https://github.com/asyncapi/bindings/issues/87 and I'm fully supporting any decision that community experienced with jms take. I know some time ago Solace folks talked about it and I bet there are others.

but, I do know I need a good example, and I bet people that will review hackathon submissions might also not have much experience with jms. So what about ActiveMQ, is it open source, afaik supports JMS. Why not provide an example based on ActiveMQ where user can run ActiveMQ on local and play with it using the generated application?

[rcoppen]

@derberg it's an API and it's not a wire protocol so it's not possible to be generic at that level. Vendor lock-in is avoided by recompiling with the right jars for your message provider. So the jms code that is output just needs to be compiled with the right jars i.e., at the maven step. However, ibmmq is also a valid AsyncAPI protocol just like mqtt or Kafka so to throw it out because we've implemented a valid protocol seems harsh, especially as it's 95% of the job for another jms provider to get value. One observation is the AsyncAPI binding for jms is currently empty. In summary, I think we can put both ibmmq and jms.

[derberg]

it's an API and it's not a wire protocol so it's not possible to be generic at that level. Vendor lock-in is avoided by recompiling with the right jars for your message provider

to the level I know Java, I guess it means that it is about API common interfaces and at a build time you just provide your specific interfaces implementation. Makes sense to me now

However, ibmmq is also a valid AsyncAPI protocol just like mqtt or Kafka so to throw it out because we've implemented a valid protocol seems harsh, especially as it's 95% of the job for another jms provider to get value

😄 I would argue that it is harsh thinking I'm saying to throw away something 😄 We are not discussing here if the project should be accepted as AsyncAPI org project or not. It is not the right time and place, and I'm not a gate keeper. I'm just sharing my feedback with you folks because of the hackathon submission. We will have 10 ppl there judging projects, with different background and some can be JSM noobs like me that first thinks about AsyncAPI from WebSocket perspective. So I'm asking you all these noob questions to help you improve the submission and make it super clear there what is the project purpose.

Just all you shared, make it clear in readme and submissions especially, make it clear that it can work not only with IBM MQ, have separate heading about it. Don't get declined just because it was not clearly described and noticed by reviewer.

Regarding the original project, have some explanation on what parts of the template require a contribution to add other JSM client support. I'm not pom.xml expert but looks like IBM client is now hardcoded https://github.com/ibm-messaging/mq-asyncapi-java-template/blob/main/components/PomHelper.js.

binding for jms is currently empty

yes, I linked the issue created by the person that wants to contribute. Basically, gates are open to contribute and take over the responsibility for the binding.

In summary, I think we can put both ibmmq and jms

What do you mean?

[rcoppen]

I'm not in disagreement. There is confusion between messaging APIs,messaging protocols and AsyncAPI protocols. JMS is a sweet-spot for the overloading of terms. The team want to showcase JMS, but to do that with a demo we have to pick a provider and went withIBM MQ which comes with a free developer edition container to test with. In this case they are showing JMS over ibmmq. However, while the JMS api allows you to recompile between providers simply by swapping implementation jars, the AsyncAPI document will include vendor specifics depending on the bindings. In our case that's the Connection URI. The generator therefore provides 95% of what any JMS provider needs, showcases ibmmq as an exemplar and documents the extensibility points. Therefore I think it's fair to say the template generator supports Java jms code and the ibmmq protocol. It's just about how we communicate this in the submission. Does that make more sense @derberg. @lewis-relph can you comment on the PomHelper.js

[lewis-relph]

Hi @derberg, We've supplied a small rework here that will allow other protocols to implement their own java dependencies (populate the PomHelper.js) as required.

[derberg]

@lewis-relph good smart approach!