Turn contracts into code

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 rely on contracts based on XML Schema (xsd). As they start with the contract design, they are called contract or schema first approaches.
Once 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.

We start with a simple schema shown in the following listing.





	  
    
	
    

    
	
		Performs a simple calculation
		
			
				
					
                        Operation to perform
                        Operation zur Ausf├╝hrung
                    
				
				
					First value
				
				
					Second value
				
			
		
	
    
	
		Result of a simple calculation
		
			
				
					Result
				
			
		
	
    

   
   	  Provides error information
      
         
				
					Fehlermeldung
				
				
					Fehlercode
				
         
      
   
	
    
    
    

	
	 
	    Defines the arithmetic operations
		
			Add
			Substract
			Multiply
			Divide
		
	

        
          
            
            
          
        



The schema is part of an example project which can be downloaded here.

A more appealing representation would look as follows:

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:

xjc calculator.xsd

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.



	org.jvnet.jaxb2.maven2
	maven-jaxb2-plugin
	0.8.1
	
		
			
				generate
			
		
	
	
		${project.basedir}/src/main/resources/xsd
		${project.basedir}/src/main/resources/xsd  
                net.pleus.services.calculator.api.model
	


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 to be generated for an xsd:date type you can use the following binding:



    
      
        
       
 

Just drop the file jaxbbinding.xjb in the the same directory as your xsd file.

The foundation
We now have a simple Java class without any additional features:

JAXB comes with very useful plugins to pimp our generated code.

HashCode, equals, toString
If we want standard operations such as hashCode, equals or toString we can use the plugin org.jvnet.jaxb2_commons:jaxb2-basics.

This gives us:

Value Constructor
If we want value constructors, we can use the plugin org.jvnet.jaxb2_commons:jaxb2-value-constructor.

The result is:

Fluent APIs
Fluent APIs can be generated with the plugin net.java.dev.jaxb2-commons:jaxb-fluent-api.

This gives us a very nice fluent API to produce intuitive and readable code.

Bean Validation
One great aspect of schema first design is that one can nicely define types and constraints like tns:decimal9F2 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 generates JSR349 compliant bean validation annotations from our XSD types. After running the build we get annotated classes shown below for valueA which appears in the xsd as tns:decimal9F2:


@NotNull
@Digits(integer = 7, fraction = 2)
protected BigDecimal valueA;

To trigger the validation from your code we just need the following code snippet:


import javax.validation.*;

ValidatorFactory validatorFactory = Validation.buildDefaultValidatorFactory();
Set<ConstraintViolation<PerformSimpleCalculationRequest>> violations = validatorFactory.getValidator().validate(request);
for(ConstraintViolation<PerformSimpleCalculationRequest> violation : violations){
  System.out.println("Violation: " + violation);
}

Javadoc
And finally it would be nice to have the documentation from within the XSD file in the generated Java code as well.
This can be achieved by the org.dpytel.jaxb:xjc-javadoc plugin.

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.

The entire plugin configuration is shown here:



	org.jvnet.jaxb2.maven2
	maven-jaxb2-plugin
	0.8.1
	
		
			
				generate
			
		
	
	
		true
		>net.pleus.services.calculator.api.model
		
			-Xinheritance
			-XtoString
			-XhashCode
			-Xequals
			-Xvalue-constructor
			-Xfluent-api
                        -XJsr303Annotations
		
		${project.basedir}/src/main/resources/xsd
		${project.basedir}/src/main/resources/xsd
		
			
				org.jvnet.jaxb2_commons
				jaxb2-basics
				${jaxb2-basics.version}
			
			
				org.jvnet.jaxb2_commons
				jaxb2-value-constructor
				${jaxb2-value-constructor.version}
			
			
				net.java.dev.jaxb2-commons
				jaxb-fluent-api
				${jaxb-fluent-api.version}
			
			
     				com.github.krasa
				krasa-jaxb-tools
				${krasa-jaxb-tools.version}
			
                        
		                org.dpytel.jaxb
  		                xjc-javadoc
		                ${xjc-javadoc-version}
		        
		
	


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 to turn the contract into code.

In part two I’m going to show how to turn contracts in into documentation.

Leave a Reply

You can use these HTML tags

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

  

  

  

*