API V2: Add Java implementation for the ModelServerClient

[cdamus]

Add/refine the Java client for API v2 endpoints that correspond to API v1, but of course with their additional capabilities, especially JSON Patch for editing. This specifically excludes a client API for the api/v2/transaction endpoint which is intended for use only by the modelserver-node layer.

• add an EMF implementation of the JSON Patch model to use in the client API
• add a codec-based subscription listener for payloads as EObjects, which enables Java-friendly access to the JSON Patch model update notifications
• update v2 client API signatures for new server capabilities, especially JSON patches in edit responses and subscriptions
• update example client to demonstrate new API v2 capabilities

Fixes #172.

Contributed on behalf of STMicroelectronics.

[cdamus]

The builds are now all broken by the removal of the Orbit repository.

[ndoschek]

Hi @cdamus! With #199 I updated the targetplatform to use the current Eclipse release 2022-03. So at least the Jenkins Build should succeed again. With the GitHub action builds there are issues we should investigate (see also #200). But if the local and Jenkins builds succeed we are good to go for now I'd say (although this is not too nice of course). I will have a look at your PR today :eyes:

[cdamus]

Hi, @ndoschek. Commit 484e92509f5f47da94875b7dd5c0aa7887479ee1 makes a bunch of changes to streamline the API and example application, pursuant to off-line discussion:

• rename the CodecSubscriptionListener class as EObjectSubscriptionListener
• rework inference of value types in JSON Patches via a back-channel push of the model root EClass from the client
• refactor existing AbcToEObjectSubscriptionListener classes as subclasses of EObjectSubscriptionListener
• only parse incremental update as a JsonPatch in API v2 or later
  • this motivates some clean-up of APIVersion parsing and convenience constants
  • add specific subclass hooks for JsonPatch and CCommandExecutionResult variants of the incremental update
• rework the ecore pseudo-format for subscriptions in the example client as an optional "as eobject" command argument
  • support the same modifier in the getcommand
  • this also made the new shortcut for JSON-to-EObject subscription superfluous, so that is removed
• remove from the V2 client API the edit(...) method with EditContext web-socket that was never implemented on the server end
• update the README for v2 API changes:
  • the new V2 client interface summary
  • simple example of client API usage
  • example of subscription listener API usage

[cdamus]

Commit e66317f267bfb8ef65e65c10ea21fb4753414ba8 fixes the copyright headers in the generated code (Eclipse code folding FTW!) and removes the superfluous constructor argument in the TypedSubscriptionListener class. While I was in there, I thought I should add some doc comments.

Regenerating the model also fixed an inconsistency in the generated code's metadata for the stringValue() operation that originally had been named valueString() but which at some point I had renamed as stringValue(). But in that refactoring exercise I had neglected to regenerate the package metadata. So, happily that is now fixed.

[cdamus]

@ndoschek there are still two Checkstyle problems in the EMF-generated doc comments in XyzImpl classes. It is strange because

• these doc comments are functionally empty like so many others in an EMF-generated implementation class
• these two specific citations by Checkstyle occur only on the doc comment of the method following a method that is annotated as @generated NOT. Oddly, not on that annotated method. This cannot be a coincidence

This is surprising and unnecessary because in general I would ignore Checkstyle on generated code. What shall I do about this?

[tortmayr]

@cdamus AFAIK the modelserver.edit package should already exclude generated sources from checkstyle checks. At least at the current master: https://github.com/eclipse-emfcloud/emfcloud-modelserver/blob/7fc1da39770697e93993ff8310ad6ead0c7472e2/bundles/org.eclipse.emfcloud.modelserver.edit/.checkstyle#L14 I guess we should make sure that the maven checkstyle check also excludes the src-gen directories. (see the glsp-server maven config as a reference)

[cdamus]

Thanks @tortmayr . It looks like this .checkstyle config is already trying to exclude the src-gen folder:

 <file-match-pattern match-pattern="src-gen" include-pattern="false"/>

I suppose that isn't working? Or it's used only by the Eclipse Checkstyle plug-in?

[tortmayr]

I suppose that isn't working? Or it's used only by the Eclipse Checkstyle plug-in?

It is working but only for the Eclipse checkstyle plugin. The maven plugin needs be configured separately. e.g:

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-checkstyle-plugin</artifactId>
        <version>${checkstyle.plugin}</version>
        <configuration>
            <configLocation>emfcloud-checkstyle-8.44.xml</configLocation>
            <consoleOutput>true</consoleOutput>
            <excludes>**/src-gen/**/*.java</excludes>
        </configuration>
        ...
       </plugin>

[cdamus]

Well, for whatever reason, no variation of <excludes> configuration that I tried actually caused Checkstyle to skip the files in the src-gen/ tree:

• <excludes>**/src-gen/**/*.java</excludes>
• <excludes>**/src-gen/**/*</excludes>
• <excludes>src-gen/**/*</excludes>
• <excludes>**/src-gen/**</excludes>
• <excludes>src-gen/**</excludes>
• etc.

So, in commit aacddfb108cf7d7b37e9bcbe13a2ba779d64b8f7 I resorted to a suppression filter to skip Javadoc checks on these files that it seems Checkstyle just insists on checking.