Hello, my dear guests. In this post I would like to show how create a web-service basing on his contract. Oracle SOA Suite and Spring Framework are chosen as a service technological platform.
The first step for every solution implementation is just right describe the problem. For the demonstration, let's choose an easy task, a well-known four arithmetic operation calculator. This case is very well because it lets us show how to provide as syntax (only natural number can be assigned) as well semantic (the division by zero exception) data validation and verification.
The service contract is defines as a WSDL document. For Oracle SOA Suite, just an abstract WSDL, which includes messages and a port type, is enough. The content of the WSDL is the following:
There are four operations in the CalculatorServicePortType: Plus, Minus, Mul and Div, each one applies a corresponding messages as an input. The message contains an element of the tBinaryOperation type and yields a result message, which contains a tResult element.
The Mediator service component is an analog of enterprise bus working inside a composite in the SCA terms. This service component filters, validates, transforms and routes messages. In the considered example, Mediator is used to transform the described in the service contract input messages into the messages used for the service business logic. Also, Mediator is a point for the syntax and semantic validation of input messages.
Just move the Mediator icon from the Component Palette in JDeveloper in the main field. The Mediator configuration wizard will be shown.
In the wizard there are two fields: Mediator name and a template for a new mediator. Because we are implementing the contract-first approach, the Interface Definition from WSDL template and the WSDL-file should be chosen.
After the 'OK' button, the mediator will be created as well as the Input_ep adapter. The adapter is an input point for the created composite and it implements the service interface.
Oracle SOA Suite starting from the 11.1.1.3 version provides the Spring Framework service component for the business logic implementation. The Spring item should be moved from the Component Palette to the main field, and the Spring Context configuration wizard will be shown. The wizard has two fields for the component name and the context file.
The source code of the created for the Spring Context classes and interfaces will be put in the 'src' sub-directory of the composite source code directory. The 'Calculator' interface hides the implementation of the service from their consumers. For interface creation, there is the New... -> General -> Java, Java Interface menu.
A name of the interface and his java package should be specified in the shown window.
The the directory for the source codes has to be specified, I suggest choose the 'path-to-the-composite/src' one.
The source code of the Calculator interface is the following:
The implementation is put in the CalculatorImpl class. The code is simple, each method just implements the corresponding arithmetic operation. The class doesn't provide any validation because it is a concern of the Mediator to do so.
The Spring context contains a definition of the Calculator bean. The bean is implemented by the name.samolisov.service.CalculatorImpl and is published as the CalculatorService service, which described by the name.samolisov.service.Calculator interface.
The project has to be compiled before it will be possible to bind the Spring Context to the Mediator. There is the Make (Ctrl + F9) and Rebuild (Alt + F9) menus in JDeveloper. After successful binding, a warning about the Calculator.wsdl creation will be shown.
Let's press OK and the binding configuration window will be here. The 'Plus' operation from the initial service contract is binding with the 'plus' operation from the created Calculator.wsdl file.
The last thing for today, is to configure the routing, transformation and message validation in the Mediator component. The editor of .mplan-files is taken to account for the configuration changing.
The Validate Syntax (XSD) checkbox has to be switched on for each validated operation. The validation by an XSD schema protects the service from assigning characters instead of numbers as the input data, for example.
Message routing is configured by using the Select an existing mapper file or create a new one on the Transform Using lines.
In the shown window there are two options: using a new transformation file or leverage an existing mapper file, because there isn't any existing one, the 'create new' option has to be chosen.
A visual XSLT editor windows will be shown. The windows is used for the message transformation configuration. For the considered example, there has to be a very trivial one, just assign the value of the a parameter to the arg0 one and the value of the b one to the arg1 one.
The transformation for the response is configured in the similar manner.
The operation Plus is ready. Each other operation is configured in the same manner, the big green plus icon and the static routing rule operation are used for creation a new operation.
There are a object types for the message routing. Our point is the Service, it does mean route a message to the service input.
The Target Service windows will be shown, the CalculationService from the BusinessLogic component and a corresponding operation have to be chosen as a target.
The warning about an existing Java interface and a corresponding WSDL interface generation will be shown here.
There are a number of rules for the generation: still the existing WSDL file, edit the chosen one and generate a new file adding a suffix to the name of the original one.
Message validation and transformation are configured as shown for the 'Plus' operation below.
The Div operation requires addition validation. Arithmetic rules deny division by zero, so we must be sure before do a service invocation. The Schematron is taken into account for semantic validation. The Schematron code is a trivial XML document, which has the .sch filename extension. JDeveloper provides the New... -> General -> XML, XML Document master for the this sort of files creation.
The filename with the .sch extension and a directory for the file have to be specified in the window.
The content of the created file div.sch:
We should ensure the value of the /types:Div/types:b parameter isn't equal to zero or show the defined warning.
The div.sch file is being connected to the Mediator using the Validate Semantic button near the corresponding operation.
The Add Validation window will be here, the validated part of a message has to be selected as well as a Schematron file.
After the OK button, there will be shown a window displays the attached to the Mediator validations. Addition validations could be added using the big grin plus sign button.
After the composite is deployed on a Oracle SOA Suite server, the CalculatorService service is available for testing. Let's check the service just invoke his operations assigning some different values. Firstly, the service calculate a number value as defined.
Then, let's assign some characters as an argument of the Plus operation. The validation error has to be returned because the syntax validation is switched on.
And the last test is the handling of a division by zero. The ORAMED-01301: [Payload Custom Validation] message contains the defined in the div.sch file has to be returned.
A practical demonstration of contract-first service design approach has been considered in the article. The business logic of the considered service was implemented based on plain-Java using the Spring Framework as infrastructure glue. Oracle SOA Suite provides a number of very usable and powerful capabilities for message transformation and validation (including the semantic validation) and the framework is integrated not only with EJB but also with good old POJOs. More information about Oracle SOA Suite and the Spring Framework could be found into the presentation.
Would you like to give a 'Like'? Please follow me on Twitter!
Service contract design
The first step for every solution implementation is just right describe the problem. For the demonstration, let's choose an easy task, a well-known four arithmetic operation calculator. This case is very well because it lets us show how to provide as syntax (only natural number can be assigned) as well semantic (the division by zero exception) data validation and verification.
The service contract is defines as a WSDL document. For Oracle SOA Suite, just an abstract WSDL, which includes messages and a port type, is enough. The content of the WSDL is the following:
There are four operations in the CalculatorServicePortType: Plus, Minus, Mul and Div, each one applies a corresponding messages as an input. The message contains an element of the tBinaryOperation type and yields a result message, which contains a tResult element.
Using Mediator for service implementation
The Mediator service component is an analog of enterprise bus working inside a composite in the SCA terms. This service component filters, validates, transforms and routes messages. In the considered example, Mediator is used to transform the described in the service contract input messages into the messages used for the service business logic. Also, Mediator is a point for the syntax and semantic validation of input messages.
Just move the Mediator icon from the Component Palette in JDeveloper in the main field. The Mediator configuration wizard will be shown.
In the wizard there are two fields: Mediator name and a template for a new mediator. Because we are implementing the contract-first approach, the Interface Definition from WSDL template and the WSDL-file should be chosen.
After the 'OK' button, the mediator will be created as well as the Input_ep adapter. The adapter is an input point for the created composite and it implements the service interface.
Business logic
Oracle SOA Suite starting from the 11.1.1.3 version provides the Spring Framework service component for the business logic implementation. The Spring item should be moved from the Component Palette to the main field, and the Spring Context configuration wizard will be shown. The wizard has two fields for the component name and the context file.
The source code of the created for the Spring Context classes and interfaces will be put in the 'src' sub-directory of the composite source code directory. The 'Calculator' interface hides the implementation of the service from their consumers. For interface creation, there is the New... -> General -> Java, Java Interface menu.
A name of the interface and his java package should be specified in the shown window.
The the directory for the source codes has to be specified, I suggest choose the 'path-to-the-composite/src' one.
The source code of the Calculator interface is the following:
The implementation is put in the CalculatorImpl class. The code is simple, each method just implements the corresponding arithmetic operation. The class doesn't provide any validation because it is a concern of the Mediator to do so.
The Spring context contains a definition of the Calculator bean. The bean is implemented by the name.samolisov.service.CalculatorImpl and is published as the CalculatorService service, which described by the name.samolisov.service.Calculator interface.
The project has to be compiled before it will be possible to bind the Spring Context to the Mediator. There is the Make (Ctrl + F9) and Rebuild (Alt + F9) menus in JDeveloper. After successful binding, a warning about the Calculator.wsdl creation will be shown.
Let's press OK and the binding configuration window will be here. The 'Plus' operation from the initial service contract is binding with the 'plus' operation from the created Calculator.wsdl file.
Mediator configuration
The last thing for today, is to configure the routing, transformation and message validation in the Mediator component. The editor of .mplan-files is taken to account for the configuration changing.
The Validate Syntax (XSD) checkbox has to be switched on for each validated operation. The validation by an XSD schema protects the service from assigning characters instead of numbers as the input data, for example.
Message routing is configured by using the Select an existing mapper file or create a new one on the Transform Using lines.
In the shown window there are two options: using a new transformation file or leverage an existing mapper file, because there isn't any existing one, the 'create new' option has to be chosen.
A visual XSLT editor windows will be shown. The windows is used for the message transformation configuration. For the considered example, there has to be a very trivial one, just assign the value of the a parameter to the arg0 one and the value of the b one to the arg1 one.
The transformation for the response is configured in the similar manner.
The operation Plus is ready. Each other operation is configured in the same manner, the big green plus icon and the static routing rule operation are used for creation a new operation.
There are a object types for the message routing. Our point is the Service, it does mean route a message to the service input.
The Target Service windows will be shown, the CalculationService from the BusinessLogic component and a corresponding operation have to be chosen as a target.
The warning about an existing Java interface and a corresponding WSDL interface generation will be shown here.
There are a number of rules for the generation: still the existing WSDL file, edit the chosen one and generate a new file adding a suffix to the name of the original one.
Message validation and transformation are configured as shown for the 'Plus' operation below.
The Div operation requires addition validation. Arithmetic rules deny division by zero, so we must be sure before do a service invocation. The Schematron is taken into account for semantic validation. The Schematron code is a trivial XML document, which has the .sch filename extension. JDeveloper provides the New... -> General -> XML, XML Document master for the this sort of files creation.
The filename with the .sch extension and a directory for the file have to be specified in the window.
The content of the created file div.sch:
We should ensure the value of the /types:Div/types:b parameter isn't equal to zero or show the defined warning.
The div.sch file is being connected to the Mediator using the Validate Semantic button near the corresponding operation.
The Add Validation window will be here, the validated part of a message has to be selected as well as a Schematron file.
After the OK button, there will be shown a window displays the attached to the Mediator validations. Addition validations could be added using the big grin plus sign button.
Composite testing
After the composite is deployed on a Oracle SOA Suite server, the CalculatorService service is available for testing. Let's check the service just invoke his operations assigning some different values. Firstly, the service calculate a number value as defined.
Then, let's assign some characters as an argument of the Plus operation. The validation error has to be returned because the syntax validation is switched on.
And the last test is the handling of a division by zero. The ORAMED-01301: [Payload Custom Validation] message contains the defined in the div.sch file has to be returned.
Conclusion
A practical demonstration of contract-first service design approach has been considered in the article. The business logic of the considered service was implemented based on plain-Java using the Spring Framework as infrastructure glue. Oracle SOA Suite provides a number of very usable and powerful capabilities for message transformation and validation (including the semantic validation) and the framework is integrated not only with EJB but also with good old POJOs. More information about Oracle SOA Suite and the Spring Framework could be found into the presentation.
Would you like to give a 'Like'? Please follow me on Twitter!
No comments:
Post a Comment