itest/databindings/readme.html - tuscany-sca-1.x - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <!--
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
  * regarding copyright ownership.  The ASF licenses this file
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
  * with the License.  You may obtain a copy of the License at
  *
  *   http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  * KIND, either express or implied.  See the License for the
  * specific language governing permissions and limitations
  * under the License.
 -->

 <html>
 <head>
   <meta http-equiv="Content-Type" content=
   "text/html; charset=us-ascii">
   <meta http-equiv="Content-Style-Type" content="text/css">

   <title>Tuscany SCA Integration Test Databindings</title>
   <!-- LINK rel="stylesheet" href="ait.css" type="text/css" -->
   <link rel="stylesheet" href="../../css/base.css" type="text/css">
 </head>

 <body>
 <h3>Tuscany SCA Integation Test Databindings </h3>

 <h4>Overview</h4>

 <p>
 This integration test tests the Tuscany SCA databinding implementation by passing various data structures
 across various bindings using the supported databindings. There are tests for the individual databindings
 which exercise various bindings with the same databinding at client and server ends of each binding. There
 is also an integration test which exercises the transformer chains by specifying different databindings at
 client and server ends of the binding.
 </p>
 <p>
 In doing this testing it is apparent that there is a lot of repetition in creating client, services, idl and
 type for each of the data types for each of the bindings for each of the databindings. To reduce the amount
 of effort required to maintain the tests as new types, bindings and databindings are added the test cases
 themselves are generated from configuration files.
 </p>

 <h4>Test Structure</h4>

 Databindings/Common             - hold files common across all tests <br/>
 Databindings/Interop            - test the transformer chains with combinations of databindings<br/>
 Databindings/sdogen and jaxbgen - test each databindings independently<br/>

 <h4>Test Generation</h4>
 <p>
 To reduce the amount of manual effort involved in building and maintaining tests cases the test cases
 themselves are generated at run time using a set of velocity templates. Each test module has a generate.xml
 file in the resources/generate directory which tells the generator what to do. The file looks like this.
 </p>
 <img src="config.png">
 <p>
 Each <Template> element describes a velocit template to use in the test. The generator process is to expand
 each velocity template provided with all of the types specified in the <InputFile> sections.
 </p>
 <p>
 Each <InputFile> element describes a schema file used in the test. It also contains a description of each
 data type that will be tested. The generator then arranges for the databinding being tested to generate
 appropriate Java classes to represent the type at runtime. The individual databinding tests use the following
 flow.
 </p>

 Create data object at client<br/>
 Client passes data object to server<br/>
 Server modifies data object<br/>
 Server returns modified data object to client<br/>
 Client tests that modified data object is as expected<br/>
 <p>
 Hence the CreateTypeCode, ModifyTypeCode and ResultComparison elements which contain the type specific code
 that is used in the tests.
 </p>

 <h4>The Common Directory</h4>
 <p>
 The common directory contains the information that is common across all of the tests. This includes the
 common velocity templates and the source for the generator that reads the config.xml for each test. Common
 also contains all of the data type schema as these are common across all tests. Each test pom is written so
 that the contents of the common project are expanded into the tests target directory before the test starts.
 In this way all of the common elements are available for the test generation phase and at test runtime.
 </p>

 <h4>Individual Databinding Tests</h4>
 <p>
 The individual databinding tests, for example, sdogen and jaxbgen, are mostly empty as their content is
 generated at runtime. The configuration and any test specific templates can be found in the resources/generate
 directory. Some files are hand crafted for each test and live in their static position in the tests directory
 structure.
 </p>
 <p>
 Each test uses the same scenario
 </p>
 <img src="databinding.png">
 <p>
 The interface exposed by the greeter service provides a greet method for each data type being tested, for
 example,
 </p>
 <code>
 PersonType greetPersonType(PersonType param);<br/>
 AttributeComplexType greetAttributeComplexType(AttributeComplexType param);<br/>
 AttributeReferenceComplexType greetAttributeReferenceComplexType(AttributeReferenceComplexType param);<br/>
 </code>
 <p>
 These methods are taken from the SDO databinding test and hence PersonType, AttributeComplexType, etc. will
 have been generated by the SDO static type generator.
 </p>
 <p>
 Hence this tests a single databinding across a variety of data types and a variety of bindings. New bindings
 be tested by extending the composite. Be datatypes can be tested by updating the confix.xml file.
 </p>
 <h4>Databinding Interoperability Tests</h4>
 <p>
 This test uses the generated client, services and types from the individual databinding tests. It does not
 regenerate them and you will see a dependency in the interop test pom on the other databinding tests. Is also
 has some generate elements because the composite file must currently have import statements for all of the
 SDO factories required during tested.
 </p>
 <p>
 The scenario used here is,
 </p>
 <img src="interop.png">
 <p>
 A chain of components is built up for each binding. Each component, drawn from the the inidividual databinding
 tests, tests the full range of datatypes. The client components are designed so that they can be chained together
 and so tranformations across different databindings is tests. The service component simply changes the data
 content and returns it as before.
 </p>
 <h4>Building And Running The Tests</h4>
 <p>
 The tests can be built by doing the following.
 </p>
 <code>
 cd sca/itest/databindings <br/>
 mvn
 </code>
 <p>
 The only modification to this process is required if a new input file is added to the tests suite. In this
 case you will need to edit the config.xml files as appropriate but run mvn twice. This may sound a little
 odd but currently the sdo test uses its pom file to generate the require SDO types. As the test is self
 generating the pom file will not be updated to include the new type file until the second time it's run. The
 aim is at some point to remove this feature from the pom.
 </p>


 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
	<!--
	* Licensed to the Apache Software Foundation (ASF) under one
	* or more contributor license agreements. See the NOTICE file
	* distributed with this work for additional information
	* regarding copyright ownership. The ASF licenses this file
	* to you under the Apache License, Version 2.0 (the
	* "License"); you may not use this file except in compliance
	* with the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing,
	* software distributed under the License is distributed on an
	* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	* KIND, either express or implied. See the License for the
	* specific language governing permissions and limitations
	* under the License.
	-->

	<html>
	<head>
	<meta http-equiv="Content-Type" content=
	"text/html; charset=us-ascii">
	<meta http-equiv="Content-Style-Type" content="text/css">

	<title>Tuscany SCA Integration Test Databindings</title>
	<!-- LINK rel="stylesheet" href="ait.css" type="text/css" -->
	<link rel="stylesheet" href="../../css/base.css" type="text/css">
	</head>

	<body>
	<h3>Tuscany SCA Integation Test Databindings </h3>

	<h4>Overview</h4>

	<p>
	This integration test tests the Tuscany SCA databinding implementation by passing various data structures
	across various bindings using the supported databindings. There are tests for the individual databindings
	which exercise various bindings with the same databinding at client and server ends of each binding. There
	is also an integration test which exercises the transformer chains by specifying different databindings at
	client and server ends of the binding.
	</p>
	<p>
	In doing this testing it is apparent that there is a lot of repetition in creating client, services, idl and
	type for each of the data types for each of the bindings for each of the databindings. To reduce the amount
	of effort required to maintain the tests as new types, bindings and databindings are added the test cases
	themselves are generated from configuration files.
	</p>

	<h4>Test Structure</h4>

	Databindings/Common - hold files common across all tests <br/>
	Databindings/Interop - test the transformer chains with combinations of databindings<br/>
	Databindings/sdogen and jaxbgen - test each databindings independently<br/>

	<h4>Test Generation</h4>
	<p>
	To reduce the amount of manual effort involved in building and maintaining tests cases the test cases
	themselves are generated at run time using a set of velocity templates. Each test module has a generate.xml
	file in the resources/generate directory which tells the generator what to do. The file looks like this.
	</p>
	<img src="config.png">
	<p>
	Each <Template> element describes a velocit template to use in the test. The generator process is to expand
	each velocity template provided with all of the types specified in the <InputFile> sections.
	</p>
	<p>
	Each <InputFile> element describes a schema file used in the test. It also contains a description of each
	data type that will be tested. The generator then arranges for the databinding being tested to generate
	appropriate Java classes to represent the type at runtime. The individual databinding tests use the following
	flow.
	</p>

	Create data object at client<br/>
	Client passes data object to server<br/>
	Server modifies data object<br/>
	Server returns modified data object to client<br/>
	Client tests that modified data object is as expected<br/>
	<p>
	Hence the CreateTypeCode, ModifyTypeCode and ResultComparison elements which contain the type specific code
	that is used in the tests.
	</p>

	<h4>The Common Directory</h4>
	<p>
	The common directory contains the information that is common across all of the tests. This includes the
	common velocity templates and the source for the generator that reads the config.xml for each test. Common
	also contains all of the data type schema as these are common across all tests. Each test pom is written so
	that the contents of the common project are expanded into the tests target directory before the test starts.
	In this way all of the common elements are available for the test generation phase and at test runtime.
	</p>

	<h4>Individual Databinding Tests</h4>
	<p>
	The individual databinding tests, for example, sdogen and jaxbgen, are mostly empty as their content is
	generated at runtime. The configuration and any test specific templates can be found in the resources/generate
	directory. Some files are hand crafted for each test and live in their static position in the tests directory
	structure.
	</p>
	<p>
	Each test uses the same scenario
	</p>
	<img src="databinding.png">
	<p>
	The interface exposed by the greeter service provides a greet method for each data type being tested, for
	example,
	</p>
	<code>
	PersonType greetPersonType(PersonType param);<br/>
	AttributeComplexType greetAttributeComplexType(AttributeComplexType param);<br/>
	AttributeReferenceComplexType greetAttributeReferenceComplexType(AttributeReferenceComplexType param);<br/>
	</code>
	<p>
	These methods are taken from the SDO databinding test and hence PersonType, AttributeComplexType, etc. will
	have been generated by the SDO static type generator.
	</p>
	<p>
	Hence this tests a single databinding across a variety of data types and a variety of bindings. New bindings
	be tested by extending the composite. Be datatypes can be tested by updating the confix.xml file.
	</p>
	<h4>Databinding Interoperability Tests</h4>
	<p>
	This test uses the generated client, services and types from the individual databinding tests. It does not
	regenerate them and you will see a dependency in the interop test pom on the other databinding tests. Is also
	has some generate elements because the composite file must currently have import statements for all of the
	SDO factories required during tested.
	</p>
	<p>
	The scenario used here is,
	</p>
	<img src="interop.png">
	<p>
	A chain of components is built up for each binding. Each component, drawn from the the inidividual databinding
	tests, tests the full range of datatypes. The client components are designed so that they can be chained together
	and so tranformations across different databindings is tests. The service component simply changes the data
	content and returns it as before.
	</p>
	<h4>Building And Running The Tests</h4>
	<p>
	The tests can be built by doing the following.
	</p>
	<code>
	cd sca/itest/databindings <br/>
	mvn
	</code>
	<p>
	The only modification to this process is required if a new input file is added to the tests suite. In this
	case you will need to edit the config.xml files as appropriate but run mvn twice. This may sound a little
	odd but currently the sdo test uses its pom file to generate the require SDO types. As the test is self
	generating the pom file will not be updated to include the new type file until the second time it's run. The
	aim is at some point to remove this feature from the pom.
	</p>


	</body>
	</html>