How to correctly embed Babbler into third-party application?

Original report by Zhanat S. Skokbayev (Bitbucket: fleissf, ).

Hi Christian,
I hope you are doing well in this strange time of coronavirus!

My question is what you suggest as the best strategy to embed Babbler as a network module into some third-party network application?

What I exactly mean is that as I wrote before we are creating an MMORPG using XMPP as the main network protocol connecting game clients and servers.
https://bitbucket.org/sco0ter/babbler/issues/154/is-it-possible-to-use-babbler-as-base
During the last year, we've separately implemented all parts of our target system and now we're going to finish integration of all these parts into a single software system (yep, it took more time than we'd expected but all is well that goes well :). As I said, we're using Babbler as the XMPP client library embedded into our game client. For the sake of studying and understanding better the XMPP Protocol, at the moment we're using Apache Vysper XMPP Server linked to the EJB Application on the server side. We've designed an MMOG XEP (actually it's based on MUC XEP, XEP-0196 User Gaming, and Multi-User Gaming) and implemented this XEP as extensions in Babbler and Apache Vysper. In general, all is working sufficiently well, but I faced a problem on how to better run Babbler through the game client:

Is it always better to run Babbler as a separate execution thread and exchange messages with it by listeners (that imposes overheads of multithreading management, testing, debugging etc.)?
Is it possible to build the Babbler's execution loop into the main thread of the game client? Our game client consists of several components, and the most important of them is the jMonkeyEngine Game Engine. The game engine has its own main execution loop and can update every linked component every 17-20 milliseconds in average (60 fps).

Please, would you clarify by what architectural decisions Babbler is guided for such cases. I would appreciate it if you could provide some sample project or code snippets on how to better run Babbler as an embedded network client.

Sorry if this question was already answered earlier but I've carefully checked all Babbler's documentation and issues and didn't find the answer.

Original comment by Christian Schudt (Bitbucket: sco0ter, GitHub: sco0ter).

Hi Zhanat,

‌

sorry for the late response…

Honestly I don’t fully understand your question. Do you want to use jMonkeyEngine’s thread for listening to inbound messages?

This commit f188a6b85aaa7928ca905ba7f2ce8d1d21ed262e allows to set a custom Executor.

Do you mean like this?

‌

Original comment by Zhanat S. Skokbayev (Bitbucket: fleissf, ).

Hi Christian,

Very glad to hear from you again! Don't worry about the late response. Finally, I tried several decisions, found the best working one, and ... and understood what I'd exactly meant.

I receive notifications about your commits and am pleased that you continue to develop Babbler.

Any way, thank you indeed for the proposed custom Executor mechanism, it's very interesting one and we'll definitely try it in the future.

At the moment we run Babbler in a separate thread and exchange data with it via listeners. All is working sufficiently well. We've almost finished implementing the feature list for the alpha version of our game, and we're planning to publish the alpha version in the next three months. Before publishing the alpha version we're planning to review our source codes, optimise them, improve, etc.

In the last year I prepared several questions on Babbler and wanted to question you after or just before publishing the alpha version, but I'd like to take advantage of this opportunity and question you now:

(1) In fact my question in this issue was that Babbler lacks of documentation and especially of architectural documentation. Babbler is perfectly javadoced and fully test covered, but it has only basic documentation on how to use it, and it has no documentation on what its architecture is, how it is organised, what concepts and abstractions it is based on, etc.

I know that some developers believe that source codes are self-sufficient, but it works only for trivial programs. XMPP is the complex network protocol and already because of that Babbler can't be a trivial piece of software.

Unfortunately, I can't propose you our help at this point because no one knows some program better than its creator. However, I can propose you my help at the next point.

(2) Have you considered to improve formatting of Babbler's source codes in accordance with at least Sun's Java Code Conventions?

For example, code lines without wrapping and mixing of methods with different access modifiers are real problems for us.

You are using very advanced style of programming which includes complex object-oriented and functional structures with tricky code patterns. I think that compliance with some formal code conventions would make Babbler clearer and more understandable, and in result increase its popularity.

If you would be interested in that improvement then we, you and me, could determine which code conventions can be additionally implemented in Babbler, and I am ready to spend a couple of weeks to help you re-format Babbler's source codes.

(3) On the server side we use EJB-envelopped Apache Vysper XMPP Server and it also works sufficiently well, so we plan to continue using this combination in the mid-term perspective.

However, I understand that in the long range only XMPP Protocol Server embedded into the Jakarta EE Container (probably, into the Web Container) will be the most productive and efficient decision.

However, if we want to implement XMPP Protocol Server within the Jakarta EE's Web Container in "the right way" then at first we have to compose a specification determining requirements that an implementation must meet in order to be an implementation of the Jakarta XMPP API, for example, similarly to the specification of the WebSocket Protocol and Jakarta WebSocket API:

https://jakarta.ee/specifications/websocket/2.0/

What do you think on that, Christian? Maybe the right way is to start the server with a specification and not with an implementation?

Frankly speaking, I still can't imagine how to embed XMPP Protocol into the Jakarta EE's Web Container, because there are a lot of stuff from the both sides and we need some tool to tie them together.

‌

Once again, sorry if I’ve missed some updates on Babbler's documentation and my information for some reasons is incorrect or outdated.

Original comment by Christian Schudt (Bitbucket: sco0ter, GitHub: sco0ter).

Hi Zhanat,

at (1): Actually I hoped the (non-Javadoc) documentation at http://docs.xmpp.rocks is quite useable for client development. But of course there can’t be enough documentation. Can you give more concrete examples on what it is lacking?

at (2): I am really suprised about your statement. How “mixing of methods with different access modifiers” cause real problems? Do you mean private methods on top and public on bottom?

I think I use the default IntelliJ style, which I find pretty reasonable and regularly “reformat” and “rearrange” the code according to IntelliJs style.

I wrap code lines usually only for long lambda expressions and the builder pattern or similar fluent API, which I think are more readabe then.

Actually I don’t feel a need to deviate from the default IntelliJ style. Do you have more concrete examples what you feel is wrong?

at (3): I’d love to have an XMPP implementation run on Jakarta EE and even started working on it in the xmpp-server module since about the last 1-2 years. However, there’s a lot of struggle with it and a lot of things to consider, e.g. finding the correct abstractions for both server and client, SSL, socket serving, authentication, routing, …. I had to refactor a lot of the client code so that it’s reusable on the server side, e.g. extract Connection and Session interface, refactor Service Discovery and Entity Capabilities, etc to at least cover some basics.

I think XMPP is more complex than other EE specs I know (like CDI, WebSockets, JPA, JAXB) and in fact my implementation even makes use of all of them. So it’s hard to define some EE spec for XMPP without actually having an implemention to proof the concept.

I also think whole teams and expert groups work on the other EE specs, I am pretty much alone here.

I’d prefer to have an implementation first, before talking about an official EE API, because I still can hardly imagine how it would look like.

Original comment by Zhanat S. Skokbayev (Bitbucket: fleissf, ).

ok, Christian,

Thanks a lot for your quick response, and sorry for the delay in my response, since I had to prepare myself.

First of all, I have to make a couple of preliminary statements:

(a) As I previously said, my questions were posed in advance. It means that I wanted to write to you after having the alpha version of our game being published, and I could show you what we've done in our project. In any case, I present you some part of my arguments now and we can return to our discussion later.

(b) I'm in Java since 1.3 (2001) and heavily a Java EE guy. For 13 years I developed corporate IT systems and strongly attached to such things as software architecture, patterns, specs, docs, etc. Moreover, developers around me have been always the same as me. So it's very possible that my estimations bear some kind of professional deformation, although we can revise my arguments together.

Now, I respond to the questions in order.

Original comment by Zhanat S. Skokbayev (Bitbucket: fleissf, ).

(1) The most useful resources that helped me a lot to use Babbler correctly (well, I hope!) are the following:

a. http://docs.xmpp.rocks/

b. http://babbler-xmpp.blogspot.com/

c. https://bitbucket.org/sco0ter/babbler/src/master/xmpp-sample/

And yes, even the last one where I found several very useful diagrams and code snippets. And that is exactly what I'm writing about. Babbler's documentation lacks of diagrams. Yes, I noticed that you have added new diagrams to the docs and they are very useful, especially here:

https://sco0ter.bitbucket.io/babbler/basics.html

https://sco0ter.bitbucket.io/babbler/debugging.html (the visual debugger is super!)

https://sco0ter.bitbucket.io/babbler/buildinstructions.html

However, I'd like to see architectural diagrams which would show how Babbler is organised, how Babbler works. At the moment, the Babbler's docs show how to use Babbler and that's correct, that's useable and useful, but it's only basic. I'd like to know not only how to use Babbler, but why Babbler is used like this.

And my question for this issue was exactly about that: do I have to run Babbler always as a separate thread or I can use other options to run Babbler from my program? If I better understood the Babbler's architecture then I could find different solutions by myself and maybe brought them to the master project (Babbler), that could promote Babbler to new audience and increase its popularity.

Finally, software architecture is about what software developers thought of when they wrote this piece of software. In other words, I'd like to know what you thought when you wrote Babbler, how you imagined Babbler, which concepts and abstractions you putted into Babbler.

The official definition of software architecture is as follows (I prefer this one):

https://www.synopsys.com/glossary/what-is-software-architecture.html

The software architecture of a system depicts the system’s organization or structure, and provides an explanation of how it behaves. A system represents the collection of components that accomplish a specific function or set of functions. In other words, the software architecture provides a sturdy foundation on which software can be built.

An example of architectural diagram (that I have at my fingertips at the moment):

https://docs.oracle.com/cd/B19306_01/appdev.102/b14256/sdo_net_concepts.htm#CIHDJHBE

Please, don't get me wrong.

I understand that documentation for large corporate products is written by separate people. However, an architectural section in the Babbler docs could be composed of several paragraphs and several diagrams - and that's all! And this section will be definitely useful!

Another point that I demand you is to document just the architecture of Babbler and not of XMPP, i.e. the architecture of the implementation and not of the protocol (of course, as far as it's possible).

Original comment by Zhanat S. Skokbayev (Bitbucket: fleissf, ).

(2) The question of coding conventions isn't about IDE.

I worked on almost all Java IDEs existed since Borland JBuilder, and the question of Java Coding Conventions isn't about IDE. It's about readability.

https://sceweb.uhcl.edu/helm/RationalUnifiedProcess/manuals/java/java.htm#Coding%20Standards

Coding standards for Java are important because they lead to greater consistency within your code and the code of your teammates. Greater consistency leads to code that is easier to understand, which means it is easier to develop and to maintain. This reduces the overall cost of the applications that you create.

You have to remember that your Java code will exist for a long time; long after you have moved on to other projects. An important goal during development is to ensure that you can transition your work to another developer, or to another team of developers so they can continue to maintain and enhance your work without having to invest an unreasonable effort to understand your code. Code that is difficult to understand runs the risk of being scrapped and rewritten.

https://www.oracle.com/java/technologies/javase/codeconventions-introduction.html#16712

Why Have Code Conventions

Code conventions are important to programmers for a number of reasons:

* 80% of the lifetime cost of a piece of software goes to maintenance.

* Hardly any software is maintained for its whole life by the original author.

* Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.

* If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.

Sun's Java Code Conventions (September 12, 1997)

https://www.oracle.com/technetwork/java/codeconventions-150003.pdf

4.1 Line Length

Avoid lines longer than 80 characters, since they're not handled well by many terminals and tools.

3.1.3 Class and Interface Declarations

Methods: These methods should be grouped by functionality rather than by scope or accessibility. For example, a private class method can be in between two public instance methods. The goal is to make reading and understanding the code easier.

Oracle Code Conventions for the Java Programming Language (April 20, 1999)

https://www.oracle.com/java/technologies/javase/codeconventions-contents.html

4.1 Line Length

Avoid lines longer than 80 characters, since they're not handled well by many terminals and tools.

Google Java Style Guide (Updated on May 22, 2018)

https://google.github.io/styleguide/javaguide.html

4.4 Column limit: 100

Java code has a column limit of 100 characters. A "character" means any Unicode code point. Except as noted below, any line that would exceed this limit must be line-wrapped, as explained in Section 4.5, Line-wrapping.

4.8.7 Modifiers

Class and member modifiers, when present, appear in the order recommended by the Java Language Specification.

Coding Standard and Programming Best Practices for Java.

https://www.linkedin.com/pulse/coding-standard-programming-best-practices-java-part-1-david-rios/

https://www.linkedin.com/pulse/coding-standard-programming-best-practices-java-part-2-david-rios/

https://www.linkedin.com/pulse/coding-standard-programming-best-practices-java-part-3-david-rios/

Adaptations to Google Java Style Guide

Column limit: 120(*). New widescreen monitors allow higher column limit.

Modifiers: appear in the order recommended by the Java Language Specification.

‌

Christian, as you can see, line wrapping is the widespread practice in Java, and not only for code statements but also for Javadocs. Class methods can be grouped by functionality or by scope and accessibility - it depends on agreement reached by developers. However, grouping methods by functionality isn't always transparent, because functionality often changes and after some time it's quite difficult to understand why methods are grouped in such order. That's why many developers group methods by scope and accessibility because it's simpler and clearer.

I meant exactly this when I wrote that it caused real problems: when you have got accustomed for years to follow Java Coding Conventions then working with codes which don't follow these conventions - yes, that makes things difficult. Because developers 80 % of their working time read codes and only 20 % write them. I don't want to say that the Babbler's source codes are bad formatted, not at all, but I see that they can be improved in formatting. And I believe that such improvement can increase popularity of Babbler by making it a software of enterprise-class quality.

‌

Here you can find the Google Java Style Guide's formatter for JetBrains IntelliJ IDEA (it's possible that some additional settings are required):

https://plugins.jetbrains.com/plugin/8527-google-java-format

Here the same formatter for other IDEs:

https://github.com/riosdav1/java-coding-resources/blob/master/tailored-google-java-style-formatter.xml

Original comment by Zhanat S. Skokbayev (Bitbucket: fleissf, ).

(3) Hmm, I'm not sure that XMPP needs some proof of concept against Jakarta EE, at least in technical sense. Because no one has doubt about technical possibility to implement XMPP on Jakarta EE. At least, not me. Technically, it's surely possible. That's only question of time and money. So, let's look at the formal definition:

https://en.wikipedia.org/wiki/Proof_of_concept

Proof of concept (PoC), also known as proof of principle, is a realization of a certain method or idea in order to demonstrate its feasibility, or a demonstration in principle with the aim of verifying that some concept or theory has practical potential. A proof of concept is usually small and may or may not be complete.

The key benefits of the proof of concept in software development are:

* possibility to choose the best technology stack for your software (application or web platform)

* getting a higher probability of investors' interest in the future software product

* simplifying and making it easier testing and validating ideas for the software's functionality

* receiving valuable feedback of a target audience (users) even before building a full-scope system

* onboarding first clients before an official software release

In any way, I think that developing the spec in parallel with the software makes sense.

Original comment by Christian Schudt (Bitbucket: sco0ter, GitHub: sco0ter).

Hi Zhanat,

I’ve listened to your feedback regarding the code style and implemented a lot of CheckStyle checks with the recent commits. I hope it’s better now.

Should be similar to the Google Style, but with small deviations, like in the linkedin article, e.g. 4 spaces indentation instead of only 2.

Original comment by Zhanat S. Skokbayev (Bitbucket: fleissf, ).

Hi Christian,

Thank you a lot!

I’m being noticed about your commits and glad to see how the codes are getting better in formatting.

I agree with you that 4 spaces indentation is more conventional. Normally, 2 spaces is rarely used when they need to make source codes more compact.

I hope that we could return to this topic in the nearest future, because I have other proposals to you on the coding conventions but I’d like to make them more demonstrable.

sco0ter / babbler

How to correctly embed Babbler into third-party application? #163