CPS-348 - Spike: Determine how to generate and share data updated events pojos from the event schema

CPS-348 - Getting issue details... STATUS

https://gerrit.onap.org/r/c/cps/+/121530

The objective of this spike is to define the way Java Pojo classes representing CPS events are generated and shared between services that need to use them in their code base.

Finally the spike provides some details about an implementation proposal.

How to generate classes representing events

Other project example

Policy Framework PdpStatus class represents a message that all PDP services are sending to PAP service

It is manually written.

https://github.com/onap/policy-models/blob/master/models-pdp/src/main/java/org/onap/policy/models/pdp/concepts/PdpStatus.java

CPS Proposition

CPS is using JSON Schema to specify CPS events.

For event driven architectures it is important to have a schema representing and defining the structure and the format of the data that has to be exchanged by any micro service that need to participate in the conversation. This schema is the contract that producers and consumers agrees on. It has to be carefully versioned and keeping track of potential breaking changes is important. Without such an explicit contract, the contract becomes implicit, fragile and integrating the services could be more challenging. Different options to define the event data structure and format could be JSON Schema, Apache Avro or Google Protocol Buffers. It has been chosen to start with JSON Schema that is still simple and straightforward to implement. (see CPS-191: Core and Temporal Integration Design#DataUpdatedEventSchema for additional details)

Then, having a JSON Schema to specify CPS events, we are proposing to leverage this schema to have an automatic generation for Java classes corresponding to CPS events.

This can be done with jsonschema2pojo-maven-plugin that is generating Java classes corresponding to a specified JSON Schema during generate-sources phase of default Maven lifecycle.

How to share classes representing events

Other project example

Policy Framework has a dedicated "policy-models-pdp" Maven module that contains PDP models (including classes representing messages) to be shared with other components.

This module is released and published in Nexus as Maven artifact to be imported as Maven dependency from other components.

https://github.com/onap/policy-models/tree/master/models-pdp

https://github.com/onap/policy-pap/blob/master/main/pom.xml#L69

https://github.com/onap/policy-pap/blob/master/main/src/main/java/org/onap/policy/pap/main/comm/PdpStatusMessageHandler.java#L93

CPS Proposition

For CPS, we are also proposing to have a "cps-events" Maven module that contains event classes to be shared with other components.

CPS Core being the producer of the events, this module is kept in cps repository. It is released, versioned and published to Nexus Maven repository at the same time other cps repository modules are.

Implementation proposal

New cps-event module in cps repository

• In cps repository, create a new "cps-events" Maven module with following pom file: 

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://maven.apache.org/POM/4.0.0"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.onap.cps</groupId>
        <artifactId>cps-parent</artifactId>
        <version>1.1.0-SNAPSHOT</version>
        <relativePath>../cps-parent/pom.xml</relativePath>
    </parent>

    <artifactId>cps-events</artifactId>
    <packaging>jar</packaging>

    <properties>
        <maven.install.skip>false</maven.install.skip>
        <maven.deploy.skip>false</maven.deploy.skip>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.5.4</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.jsonschema2pojo</groupId>
                <artifactId>jsonschema2pojo-maven-plugin</artifactId>
                <version>1.1.1</version>
                <configuration>
                    <sourceDirectory>${basedir}/src/main/resources/schemas</sourceDirectory>
                    <targetPackage>org.onap.cps.event.schema</targetPackage>
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

</project>

• In cps-events module, add the JSON Schema file for CPS Data Updated Events at "src/main/resources/schemas/cps-data-updated-event-schema.json". This is the only file to be kept in source control. Its version representing the event schema version should be kept aligned with "cps-events" CPS module version.
• Then, CPS event classes are automatically generated and added to "cps-events.jar" artifact each time the module is built.

CPS events classes usage

• From CPS Core and CPS Temporal, add the following pom dependency:

        <dependency>
            <groupId>org.onap.cps</groupId>
            <artifactId>cps-events</artifactId>
            <version>1.1.0-SNAPSHOT</version>
        </dependency>

• Then, both producer and consumer are able to use CPS Data Updated Event classes:

// Produce event
public void produce(final CpsDataUpdatedEvent dataUpdatedEvent);

// Consume event
public void consume(final CpsDataUpdatedEvent dataUpdatedEvent);