[deepamehta-devel] Upcoming DM 4.4: Core API Spring Cleaning

[Jörg Richter]

Dear developers,

here I like to announce one highlight of the upcoming DM 4.4 release. The DM 4.4 API is subject to a comprehensive spring cleaning. That is revising those original API concepts that turned out to make the life of the DM plugin developer more difficult than necessary. The spring cleaning includes 5 changes possibly every server-side developer will benefit from.

Along with this announcement I like to encourage every plugin developer to jump on the 4.4 train now and to adapt their plugins. Before releasing DM 4.4 I like to know if the API changes are working as expected for the various 3rd-party plugins. Also I like to offer any help required for the plugin adaption process.

All the 5 changes described in the remainder are now complete and testable via the master branch. Details about the 4.4 changes and new APIs are described in the comments of the respective ticket.


1) Service Injection

A plugin consumes the services provided by other plugins through injection. The plugin developer just needs to declare an instance variable for the desired service and annotate it with @Inject. Once the service becomes available DM cares about injecting it into the declared variable. No boilerplate code is required anymore (in terms of serviceArrived() and serviceGone() hooks).

So, in most cases the serviceArrived() and serviceGone() hooks are not required to be implemented anymore. However they still are useful in case a plugin wants to perform a certain task just in the moment when a service arrives resp. is about to be gone.

https://trac.deepamehta.de/ticket/695


2) Transactions by Annotation

A plugin developer creates a transaction just by annotation. She does so by annotating a resource method with @Transactional. DM then cares about creating a transaction on a per-request basis (it does so by the means of a Jersey ResourceFilter).

As a result the plugin developer must not create a transaction manually (that is repeating the same imperative code pattern over and over) anymore. Another benefit is that when a request combines several API calls these are guaranteed to be performed in a common transaction.

https://trac.deepamehta.de/ticket/698


So, these 2 changes provides a much more "modern" feel to the DM plugin development framework and brings it on a par with other frameworks (at least regarding the general aspects service injection and transactions).

The remaining 3 changes are specific to the DM API. Three parameters -- "directives", "clientState", "fetchComposite" -- were omnipresent in the DM API and made it difficult to use, error-prone, difficult to learn/teach/remember. All this 3 parameters are almost completely removed from all APIs. Any plugin developer who ever coded at the server-side knows that this is a true relief :-)


3) "directives" parameter removed from all APIs

In DM Directives are hints the server attaches to responses in order to support the querying client with updating its GUI. Directives are mostly constructed by the DM Core operations. Most plugins do not need to deal with directives explicitly. Nevertheless the plugin developers were required to pass a Directives object to a lot of API calls. This is not required anymore.

Now the DM Core attaches a Directives object to each request (it does so by holding it in a thread-local variable) and maintains it transparently. Plugins who need access to the directives still can do so (just by calling Directives.get()).

https://trac.deepamehta.de/ticket/697


4) "clientState" parameter removed from all APIs

In DM a ClientState object actually represented the set of cookies send along with a request. Most plugins do not deal with cookies. However the plugin developer was required to pass a ClientState object to a lot of API calls, just for the case another plugin needs to operate on it. This is not required anymore. The "clientState" parameter is completely removed from all APIs.

Again it is the DM Core who now holds a ClientState object (which is now named Cookies for obvious reasons) for each request behind the scenes (again in a thread-local variable). A plugin who needs access to the cookies of the current request just calls Cookies.get().

https://trac.deepamehta.de/ticket/696


5) "fetchComposite" parameter removed from most APIs

A lot of retrieval API calls had a boolean "fetchComposite" parameter. It controls whether the requested topic/association's child topics should be retrieved as well. This puts additional burden to the plugin developer as she must think about this setting, and possibly leads to "illegal access" errors later on in case of childs are missing due to a wrong setting.

The "fetchComposite" parameter is dropped from (nearly) all APIs. Now child topics are retrieved selectively and on-demand, that is when they are actually needed/accessed.

The only spot where the "fetchComposite" parameter still appears is in the REST APIs. This is because selective on-demand loading is not efficient over the network. However in most cases when a plugin offers a REST API the plugin developer must not care about processing a possible "fetchComposite" query parameter. In most cases it is the DM Core who processes it transparently, that is DM cares about fetching the requested child topics (it does so by the means of a Jersey ContainerResponseFilter).

https://trac.deepamehta.de/ticket/699


So, my hope is that developing (server-side) DM plugins is more fun now. That the APIs are easier to use now as well as easier to learn, to tech, and to remember. And finally that DM 4.4 will increase the acceptance on the side of the developers and that it helps increasing the DM development community.

DM 4.4 is scheduled for release end of September (we're a little late).

Cheers,
Jörg