{"id":2584,"date":"2015-02-19T17:26:31","date_gmt":"2015-02-19T16:26:31","guid":{"rendered":"http:\/\/www.pleus.net\/blog\/?p=2584"},"modified":"2017-08-25T16:40:11","modified_gmt":"2017-08-25T14:40:11","slug":"turn-contracts-into-code","status":"publish","type":"post","link":"https:\/\/www.pleus.net\/blog\/?p=2584","title":{"rendered":"Turn contracts into code"},"content":{"rendered":"

Interfaces are one of the most important parts in software design. Designing software around properly defined interfaces has many benefits for instance in the areas of consistency, maintainability and reuse. A well written contract describes precisely how software artefacts (or services) interact with each other. Approaches such as Sustainable Service Design<\/a> or the BiPRO<\/a> standards rely on contracts based on XML Schema (xsd). As they start with the contract design, they are called contract or schema first<\/a> approaches.
\nOnce you have a contract the question is how to turn it into code. In the Java world JAXB is the first choice. Lets’s see how we can generate Java sourcecode from the schema.<\/p>\n

We start with a simple schema shown in the following listing.<\/p>\n

\r\n<?xml version="1.0" encoding="UTF-8"?>\r\n<?xml-stylesheet type="text\/xsl" href="contract.xsl"?>\r\n<xs:schema\r\n    xmlns:xs="http:\/\/www.w3.org\/2001\/XMLSchema"\r\n    xmlns:xml="http:\/\/www.w3.org\/XML\/1998\/namespace"    \r\n    xmlns:service="http:\/\/www.pleus.net\/services"\r\n    xmlns:tns="http:\/\/www.pleus.net\/services\/calculator\/api\/model"\r\n\ttargetNamespace="http:\/\/www.pleus.net\/services\/calculator\/api\/model"\r\n\telementFormDefault="qualified" attributeFormDefault="qualified"\r\n\tversion="1.0">\r\n\t  \r\n    <!-- ################################################### -->\r\n\t<!-- ################### Messages ###################### -->\r\n    <!-- ################################################### -->\r\n\r\n    \r\n\t<xs:element name="PerformSimpleCalculationRequest">\r\n\t\t<xs:annotation><xs:documentation>Performs a simple calculation<\/xs:documentation><\/xs:annotation>\r\n\t\t<xs:complexType>\r\n\t\t\t<xs:sequence>\r\n\t\t\t\t<xs:element name="operation" type="tns:Operation" minOccurs="1" maxOccurs="1">\r\n\t\t\t\t\t<xs:annotation>\r\n                        <xs:documentation xml:lang="EN">Operation to perform<\/xs:documentation>\r\n                        <xs:documentation xml:lang="DE">Operation zur Ausf\u00fchrung<\/xs:documentation>\r\n                    <\/xs:annotation>\r\n\t\t\t\t<\/xs:element>\r\n\t\t\t\t<xs:element name="value-a" type="tns:decimal9F2" minOccurs="1" maxOccurs="1">\r\n\t\t\t\t\t<xs:annotation><xs:documentation>First value<\/xs:documentation><\/xs:annotation>\r\n\t\t\t\t<\/xs:element>\r\n\t\t\t\t<xs:element name="value-b" type="xs:decimal" minOccurs="1" maxOccurs="1">\r\n\t\t\t\t\t<xs:annotation><xs:documentation>Second value<\/xs:documentation><\/xs:annotation>\r\n\t\t\t\t<\/xs:element>\r\n\t\t\t<\/xs:sequence>\r\n\t\t<\/xs:complexType>\r\n\t<\/xs:element>\r\n    \r\n\t<xs:element name="PerformSimpleCalculationResponse">\r\n\t\t<xs:annotation><xs:documentation>Result of a simple calculation<\/xs:documentation><\/xs:annotation>\r\n\t\t<xs:complexType>\r\n\t\t\t<xs:sequence>\r\n\t\t\t\t<xs:element name="result" type="xs:decimal" minOccurs="1" maxOccurs="1">\r\n\t\t\t\t\t<xs:annotation><xs:documentation>Result<\/xs:documentation><\/xs:annotation>\r\n\t\t\t\t<\/xs:element>\r\n\t\t\t<\/xs:sequence>\r\n\t\t<\/xs:complexType>\r\n\t<\/xs:element>\r\n    \r\n\r\n   <xs:element name="CalculatorError">\r\n   \t  <xs:annotation><xs:documentation>Provides error information<\/xs:documentation><\/xs:annotation>\r\n      <xs:complexType>\r\n         <xs:sequence>\r\n\t\t\t\t<xs:element name="message" type="xs:string" minOccurs="1" maxOccurs="1">\r\n\t\t\t\t\t<xs:annotation><xs:documentation>Fehlermeldung<\/xs:documentation><\/xs:annotation>\r\n\t\t\t\t<\/xs:element>\r\n\t\t\t\t<xs:element name="code" type="xs:int" minOccurs="1" maxOccurs="1">\r\n\t\t\t\t\t<xs:annotation><xs:documentation>Fehlercode<\/xs:documentation><\/xs:annotation>\r\n\t\t\t\t<\/xs:element>\r\n         <\/xs:sequence>\r\n      <\/xs:complexType>\r\n   <\/xs:element>\r\n\t\r\n    <!-- ################################################### -->\r\n    <!-- ################# Type definitions ################ -->\r\n    <!-- ################################################### -->\r\n\r\n\t<!--  Enum type  -->\r\n\t <xs:simpleType name="Operation">\r\n\t    <xs:annotation><xs:documentation>Defines the arithmetic operations<\/xs:documentation><\/xs:annotation>\r\n\t\t<xs:restriction base="xs:string">\r\n\t\t\t<xs:enumeration value="ADD"><xs:annotation><xs:documentation>Add<\/xs:documentation><\/xs:annotation><\/xs:enumeration>\r\n\t\t\t<xs:enumeration value="SUBTRACT"><xs:annotation><xs:documentation>Substract<\/xs:documentation><\/xs:annotation><\/xs:enumeration>\r\n\t\t\t<xs:enumeration value="MULTIPLY"><xs:annotation><xs:documentation>Multiply<\/xs:documentation><\/xs:annotation><\/xs:enumeration>\r\n\t\t\t<xs:enumeration value="DIVIDE"><xs:annotation><xs:documentation>Divide<\/xs:documentation><\/xs:annotation><\/xs:enumeration>\r\n\t\t<\/xs:restriction>\r\n\t<\/xs:simpleType>\r\n\r\n        <xs:simpleType name="decimal9F2">\r\n          <xs:restriction base="xs:decimal">\r\n            <xs:totalDigits value="9"\/>\r\n            <xs:fractionDigits value="2"\/>\r\n          <\/xs:restriction>\r\n        <\/xs:simpleType>\r\n\r\n<\/xs:schema>\r\n<\/pre>\n
The schema is part of an example project which can be downloaded here<\/a>.<\/p>\n
A more appealing representation would look as follows:
\n<\/a><\/p>\n
In order to turn this schema into code we can call the xjb tool which is part of the Java SDK on the command line like this:<\/p>\n
\r\nxjc calculator.xsd\r\n<\/pre>\n
As a result we get Java code that we can incorporate in our code base. Another option is to generate the Java code from our Maven build. This can be achieved by adding following Maven Plugin to your pom.<\/p>\n
\r\n\r\n<plugin>\r\n\t<groupId>org.jvnet.jaxb2.maven2<\/groupId>\r\n\t<artifactId>maven-jaxb2-plugin<\/artifactId>\r\n\t<version>0.8.1<\/version>\r\n\t<executions>\r\n\t\t<execution>\r\n\t\t\t<goals>\r\n\t\t\t\t<goal>generate<\/goal>\r\n\t\t\t<\/goals>\r\n\t\t<\/execution>\r\n\t<\/executions>\r\n\t<configuration>\r\n\t\t<schemaDirectory>${project.basedir}\/src\/main\/resources\/xsd<\/schemaDirectory>\r\n\t\t<bindingDirectory>${project.basedir}\/src\/main\/resources\/xsd<\/bindingDirectory>  \r\n                <generatePackage>net.pleus.services.calculator.api.model<\/generatePackage>\r\n\t<\/configuration>\r\n<\/plugin>\r\n\r\n<\/pre>\n
As a result we get basic Java classes that represent the messages and types defined in our schema. If you want to affect the way the code is generated you can provide xjb binding files to customize the generated code. If you want for example use java.util.Calendar<\/em> to be generated for an xsd:date<\/em> type you can use the following binding:<\/p>\n
\r\n\r\n<jaxb:bindings version="2.1"\r\n    xmlns:jaxb="http:\/\/java.sun.com\/xml\/ns\/jaxb"\r\n    xmlns:xjc="http:\/\/java.sun.com\/xml\/ns\/jaxb\/xjc"\r\n    xmlns:xsd="http:\/\/www.w3.org\/2001\/XMLSchema">\r\n    <jaxb:globalBindings generateElementProperty="false">\r\n      <jaxb:javaType name="java.util.Calendar" xmlType="xsd:date"  \r\n             parseMethod="javax.xml.bind.DatatypeConverter.parseDate"  \r\n             printMethod="javax.xml.bind.DatatypeConverter.printDate">\r\n      <\/jaxb:javaType>  \r\n    <\/jaxb:globalBindings>   \r\n<\/jaxb:bindings> \r\n\r\n<\/pre>\n
Just drop the file jaxbbinding.xjb in the the same directory as your xsd file.<\/p>\n
The foundation<\/strong>
\nWe now have a simple Java class without any additional features:
\n<\/a><\/p>\n
JAXB comes with very useful plugins to pimp our generated code.<\/p>\n
HashCode, equals, toString<\/strong>
\nIf we want standard operations such as hashCode, equals or toString we can use the plugin org.jvnet.jaxb2_commons:jaxb2-basics<\/em>.<\/p>\n
This gives us:
\n<\/a><\/p>\n
Value Constructor<\/strong>
\nIf we want value constructors, we can use the plugin org.jvnet.jaxb2_commons:jaxb2-value-constructor<\/em>.<\/p>\n
The result is:
\n<\/a><\/p>\n
Fluent APIs<\/strong>
\nFluent APIs can be generated with the plugin net.java.dev.jaxb2-commons:jaxb-fluent-api<\/em>.<\/p>\n
This gives us a very nice fluent API to produce intuitive and readable code.
\n<\/a><\/p>\n
Bean Validation<\/strong>
\nOne great aspect of schema first design is that one can nicely define types and constraints like tns:decimal9F2<\/em> shown in the listing at the top of this page. Wouldn’t it be nice if we could check those constraints in our code without additional effort? The plugin com.github.krasa:krasa-jaxb-tools<\/em> generates JSR349 compliant bean validation annotations from our XSD types. After running the build we get annotated classes shown below for valueA<\/em> which appears in the xsd as tns:decimal9F2<\/em>:<\/p>\n
\r\n\r\n@NotNull\r\n@Digits(integer = 7, fraction = 2)\r\nprotected BigDecimal valueA;\r\n\r\n<\/pre>\n
To trigger the validation from your code we just need the following code snippet:<\/p>\n
\r\n\r\nimport javax.validation.*;\r\n\r\nValidatorFactory validatorFactory = Validation.buildDefaultValidatorFactory();\r\nSet<ConstraintViolation<PerformSimpleCalculationRequest>> violations = validatorFactory.getValidator().validate(request);\r\nfor(ConstraintViolation<PerformSimpleCalculationRequest> violation : violations){\r\n  System.out.println(\"Violation: \" + violation);\r\n}\r\n\r\n<\/pre>\n
Javadoc<\/strong>
\nAnd finally it would be nice to have the documentation from within the XSD file in the generated Java code as well.
\nThis can be achieved by the org.dpytel.jaxb:xjc-javadoc<\/em> plugin.<\/p>\n
<\/a><\/p>\n
If you have additional needs to manipulate the generated code, you can implement your own JAXB plugin which can be hooked into the build process. This gives you maximum flexibility and full control of the code generation.<\/p>\n
The entire plugin configuration is shown here:<\/p>\n
\r\n\r\n\r\n\torg.jvnet.jaxb2.maven2<\/groupId>\r\n\tmaven-jaxb2-plugin<\/artifactId>\r\n\t0.8.1<\/version>\r\n\t\r\n\t\t\r\n\t\t\t\r\n\t\t\t\tgenerate<\/goal>\r\n\t\t\t<\/goals>\r\n\t\t<\/execution>\r\n\t<\/executions>\r\n\t\r\n\t\ttrue<\/extension>\r\n\t\t>net.pleus.services.calculator.api.model<\/generatePackage>\r\n\t\t\r\n\t\t\t-Xinheritance<\/arg>\r\n\t\t\t-XtoString<\/arg>\r\n\t\t\t-XhashCode<\/arg>\r\n\t\t\t-Xequals<\/arg>\r\n\t\t\t-Xvalue-constructor<\/arg>\r\n\t\t\t-Xfluent-api<\/arg>\r\n                        -XJsr303Annotations<\/arg>\r\n\t\t<\/args>\r\n\t\t${project.basedir}\/src\/main\/resources\/xsd<\/schemaDirectory>\r\n\t\t${project.basedir}\/src\/main\/resources\/xsd<\/bindingDirectory>\r\n\t\t\r\n\t\t\t\r\n\t\t\t\torg.jvnet.jaxb2_commons<\/groupId>\r\n\t\t\t\tjaxb2-basics<\/artifactId>\r\n\t\t\t\t${jaxb2-basics.version}<\/version>\r\n\t\t\t<\/plugin>\r\n\t\t\t\r\n\t\t\t\torg.jvnet.jaxb2_commons<\/groupId>\r\n\t\t\t\tjaxb2-value-constructor<\/artifactId>\r\n\t\t\t\t${jaxb2-value-constructor.version}<\/version>\r\n\t\t\t<\/plugin>\r\n\t\t\t\r\n\t\t\t\tnet.java.dev.jaxb2-commons<\/groupId>\r\n\t\t\t\tjaxb-fluent-api<\/artifactId>\r\n\t\t\t\t${jaxb-fluent-api.version}<\/version>\r\n\t\t\t<\/plugin>\r\n\t\t\t\r\n     \t\t\t\tcom.github.krasa<\/groupId>\r\n\t\t\t\tkrasa-jaxb-tools<\/artifactId>\r\n\t\t\t\t${krasa-jaxb-tools.version}<\/version>\r\n\t\t\t<\/plugin>\r\n                        \r\n\t\t                org.dpytel.jaxb<\/groupId>\r\n  \t\t                xjc-javadoc<\/artifactId>\r\n\t\t                ${xjc-javadoc-version}<\/version>\r\n\t\t        <\/plugin>\r\n\t\t<\/plugins>\r\n\t<\/configuration>\r\n<\/plugin>\r\n\r\n<\/pre>\n
In this post I’ve shown how to turn contracts into code on the Java platform easily. The contracts are 100% reusable, interoperable and cross platform, of instance on the .NET platform. Here you would use svcuitl.exe<\/em> to turn the contract into code.<\/p>\n
In part two I’m going to show how to turn contracts in into documentation<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"
Interfaces are one of the most important parts in software design. Designing software around properly defined interfaces has many benefits for instance in the areas of consistency, maintainability and reuse. A well written contract describes precisely how software artefacts (or services) interact with each other. Approaches such as Sustainable Service Design or the BiPRO standards … Continue reading Turn contracts into code<\/span><\/a><\/p>\n","protected":false},"author":3,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[9,3],"tags":[53,59,62,77,60,25,54],"class_list":["post-2584","post","type-post","status-publish","format-standard","hentry","category-bpm","category-soa","tag-bipro","tag-jaxb","tag-maven","tag-soa","tag-ssd","tag-xml","tag-xsd"],"_links":{"self":[{"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=\/wp\/v2\/posts\/2584","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=2584"}],"version-history":[{"count":68,"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=\/wp\/v2\/posts\/2584\/revisions"}],"predecessor-version":[{"id":3139,"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=\/wp\/v2\/posts\/2584\/revisions\/3139"}],"wp:attachment":[{"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=2584"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=2584"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.pleus.net\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=2584"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}