Change in ovirt-engine[master]: restapi: Introduce metamodel

juan.hernandez at redhat.com juan.hernandez at redhat.com
Tue Oct 27 10:10:55 UTC 2015 

Juan Hernandez has submitted this change and it was merged.

Change subject: restapi: Introduce metamodel
......................................................................


restapi: Introduce metamodel

Currently the model of the RESTAPI is defined using a XML schema. This
XML schema is processed with the JAXB "xjc" compiler and the Java
classes of the model are generated. This has several inconveniences:

1. The model is tied to the XML schema model, even if we aim to
   support both XML and JSON. JSON happens to work correctly because
   we are lucky enough that the JSON library that we use supports the
   JAXB annotations.

2. It is difficult to extract information from the XML schema. Tools
   like the generators of the SDKs have to do some ugly tricks, like
   using XPath queries and using reflection to ispect the code
   generated by the JAXB "xjc" compiler.

3. The XML schema is single giant file, more than 6000 lines at the
   moment.

In order to improve the situation this patch introduces a metamodel that
will be used to describe the data types used by the RESTAPI. This
metamodel will be written in Java, using interfaces and annotations to
describe the types. For example, to describe the bookmark type an
interface like the following will be used:

  @Type
  public interface Bookmark {
    String value();
  }

This only purpose of this interface is to describe the characteristics
of the type: its name, its attributes, etc. It isn't intended to be
implemented or used during runtime in any way. The metamodel analyzer
will inspect this source code and create a data structure easier to
digest and use for applications, like the generators of the SDKs. For
example, a tool could use the generated data structure to list the
attributes of the bookmark type as follows:

  // Analyze the model files:
  Model model = new Model();
  ModelAnalyzer analyzer = new ModelAnalyzer();
  analyzer.setModel(model);
  analyzer.analyzeSource(...);

  // Find the bookmark type and list its attributes:
  Name bookmarkName = NameParser.parseUsingCase("Bookmark");
  Type bookmarType = model.getType(bookmarkName);
  for (Attribute attribute : bookmarkType.getAttributes()) {
    System.out.println(attribute.getName());
  }

The metamodel includes also a tool that will be used to generate code
from the model. Currently it only supports generating fragmetns of the
XML schema. This is needed in order to preserve compatibility with the
current RESTAPI implementation. The tool will take the existing XML
schema, and will add to it the fragments generated to the model. This
way it is possible to gradually replace the XML schema description of
types with the equivalent Java description.

In the future the tool will be extended to generate other outputs:

* Java interfaces, containers and builders to be used during runtime,
  instead of the code currently generated by the JAXB "xjc" compiler.

* Java code used to parse and serialize XML and JSON documents using an
  streaming approach, instead of the "all in memory" approach used by JAXB
  (and also by the JSON implementation that we use).

* Documentation, extracted from the Javadoc comments of the type
  interfaces.

Change-Id: I80b036b5c3b3f9ad4d316c8f6c0a568b0465adb9
Related: https://bugzilla.redhat.com/1201197
Signed-off-by: Juan Hernandez <juan.hernandez at redhat.com>
---
M backend/manager/modules/restapi/interface/definition/pom.xml
A backend/manager/modules/restapi/metamodel/analyzer/README.md
A backend/manager/modules/restapi/metamodel/analyzer/pom.xml
A backend/manager/modules/restapi/metamodel/analyzer/src/main/java/org/ovirt/api/metamodel/analyzer/ModelAnalyzer.java
A backend/manager/modules/restapi/metamodel/analyzer/src/main/java/org/ovirt/api/metamodel/analyzer/ModelAnnotations.java
A backend/manager/modules/restapi/metamodel/analyzer/src/main/java/org/ovirt/api/metamodel/analyzer/ServiceSetter.java
A backend/manager/modules/restapi/metamodel/analyzer/src/main/java/org/ovirt/api/metamodel/analyzer/ServiceUsage.java
A backend/manager/modules/restapi/metamodel/analyzer/src/main/java/org/ovirt/api/metamodel/analyzer/TypeSetter.java
A backend/manager/modules/restapi/metamodel/analyzer/src/main/java/org/ovirt/api/metamodel/analyzer/TypeUsage.java
A backend/manager/modules/restapi/metamodel/analyzer/src/main/java/org/ovirt/api/metamodel/analyzer/UndefinedService.java
A backend/manager/modules/restapi/metamodel/analyzer/src/main/java/org/ovirt/api/metamodel/analyzer/UndefinedType.java
A backend/manager/modules/restapi/metamodel/annotations/README.md
A backend/manager/modules/restapi/metamodel/annotations/pom.xml
A backend/manager/modules/restapi/metamodel/annotations/src/main/java/org/ovirt/api/metamodel/annotations/In.java
A backend/manager/modules/restapi/metamodel/annotations/src/main/java/org/ovirt/api/metamodel/annotations/Link.java
A backend/manager/modules/restapi/metamodel/annotations/src/main/java/org/ovirt/api/metamodel/annotations/Method.java
A backend/manager/modules/restapi/metamodel/annotations/src/main/java/org/ovirt/api/metamodel/annotations/Out.java
A backend/manager/modules/restapi/metamodel/annotations/src/main/java/org/ovirt/api/metamodel/annotations/Root.java
A backend/manager/modules/restapi/metamodel/annotations/src/main/java/org/ovirt/api/metamodel/annotations/Service.java
A backend/manager/modules/restapi/metamodel/annotations/src/main/java/org/ovirt/api/metamodel/annotations/Type.java
A backend/manager/modules/restapi/metamodel/concepts/README.md
A backend/manager/modules/restapi/metamodel/concepts/pom.xml
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/Attribute.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/Concept.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/Constraint.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/EnumType.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/EnumValue.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/Expression.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/Link.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/ListType.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/Locator.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/Method.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/Model.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/Module.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/Name.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/NameParser.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/Parameter.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/PrimitiveType.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/Service.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/StructType.java
A backend/manager/modules/restapi/metamodel/concepts/src/main/java/org/ovirt/api/metamodel/concepts/Type.java
A backend/manager/modules/restapi/metamodel/pom.xml
A backend/manager/modules/restapi/metamodel/tool/README.md
A backend/manager/modules/restapi/metamodel/tool/pom.xml
A backend/manager/modules/restapi/metamodel/tool/src/main/java/org/ovirt/api/metamodel/tool/Main.java
A backend/manager/modules/restapi/metamodel/tool/src/main/java/org/ovirt/api/metamodel/tool/SchemaGenerator.java
A backend/manager/modules/restapi/metamodel/tool/src/main/java/org/ovirt/api/metamodel/tool/Tool.java
A backend/manager/modules/restapi/metamodel/tool/src/main/resources/META-INF/beans.xml
A backend/manager/modules/restapi/metamodel/tool/src/main/resources/log4j.xml
A backend/manager/modules/restapi/model/pom.xml
A backend/manager/modules/restapi/model/src/main/java/types/package-info.java
M backend/manager/modules/restapi/pom.xml
52 files changed, 3,557 insertions(+), 2 deletions(-)

Approvals:
  Ori Liel: Looks good to me, but someone else must approve
  Juan Hernandez: Verified; Looks good to me, approved
  Jenkins CI: Passed CI tests



-- 
To view, visit https://gerrit.ovirt.org/45852
To unsubscribe, visit https://gerrit.ovirt.org/settings

Gerrit-MessageType: merged
Gerrit-Change-Id: I80b036b5c3b3f9ad4d316c8f6c0a568b0465adb9
Gerrit-PatchSet: 23
Gerrit-Project: ovirt-engine
Gerrit-Branch: master
Gerrit-Owner: Juan Hernandez <juan.hernandez at redhat.com>
Gerrit-Reviewer: Barak Azulay <bazulay at redhat.com>
Gerrit-Reviewer: Jenkins CI
Gerrit-Reviewer: Juan Hernandez <juan.hernandez at redhat.com>
Gerrit-Reviewer: Ori Liel <oliel at redhat.com>
Gerrit-Reviewer: Oved Ourfali <oourfali at redhat.com>
Gerrit-Reviewer: automation at ovirt.org

More information about the Engine-commits mailing list