wood burning stoves 2.0*
The moose likes Web Services and the fly likes Well defined or generalized service contract? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of OCA/OCP Java SE 7 Programmer I & II Study Guide this week in the OCPJP forum!
JavaRanch » Java Forums » Java » Web Services
Bookmark "Well defined or generalized service contract?" Watch "Well defined or generalized service contract?" New topic
Author

Well defined or generalized service contract?

John Ranaudo
Ranch Hand

Joined: Sep 23, 2003
Posts: 31
When your defining your service contract why create a strongly typed interface as opposed to something very generic?

For example:
<IncomeStatement>
<NetSalesRevenue>100000.00</NetSalesRevenue>
<CostOfGoodsSold>75000.00</CostOfGoodSold>
</IncomeStatement>

as opposed to

<report type="IncomeStatement">
<rows id="">
<row name="NetSalesRevenue" value="100000.00"/>
<row name="CostOfGoodsSold" value="100000.00"/>
</rows>
</report>

My team and I are currently at odds to which approach has better value to our clients. I favor the first approach.

The first approach puts a data model on our service which is easy to understand while the second would require some metadata service to describe things like structure. The second approach (they prefer) is easier to consume because it does not take much logic to translate the response.

The other argument for the second selection has been that since the clients of our service know what an income statement is then they don't need structure.

Now I have read books on SOA and I understand the value of putting a model on top of your service but can anyone help me explain this benefit in a more precise way?
Peer Reynders
Bartender

Joined: Aug 19, 2005
Posts: 2922
    
    5
Originally posted by John Ranaudo:
When your defining your service contract why create a strongly typed interface as opposed to something very generic?

For example:
<IncomeStatement>
<NetSalesRevenue>100000.00</NetSalesRevenue>
<CostOfGoodsSold>75000.00</CostOfGoodSold>
</IncomeStatement>

as opposed to

<report type="IncomeStatement">
<rows id="">
<row name="NetSalesRevenue" value="100000.00"/>
<row name="CostOfGoodsSold" value="100000.00"/>
</rows>
</report>



Well, for my taste the second representation is too attribute heavy and there have been unending discussions of what belongs in an element and what belongs in an attribute, however the rule of thumb is Effective XML Item 12: Store metadata in attributes. value="100000.00" doesn't classify as meta-data. Attributes also are severely restricted as they can only have string values. Principles of XML design: When to use elements versus attributes. See also Make structure explicit through markup especially "Tag Each Unit of Information". Sometimes it makes sense to put the lowest, most unstructured pieces of information into attributes but it is important to remember that attributes so not support structure. I would judge the second representation as "simplistic", rather than "generic" - it's basically a name-value list - adding data that requires further detailed structuring has become impossible.

Make everything as simple as possible, but not simpler. Albert Einstein.


Loading Properties from XML shows an example where Java property files (which are basically name-value lists) have been converted to XML. The only real advantage achieved here is that the XML property file doesn't need a specialized parser for processing - the established properties API still restricts the structure to a name-value list so many advantages that XML may bring cannot be realized.


The first approach puts a data model on our service which is easy to understand


You may want to review Effective Enterprise Java: Item 43: Recognize the object-hierarchical impedance mismatch
Similarly data models are relational while XML Schemas are hierarchical leading to a relational-hierarchical impedance mismatch.

So ultimately "putting the data model on the service" may not be such a good idea. Given that you have chosen to represent the information with XML you should play to its strengths and weaknesses and structure the information in a representation that makes the most sense to the client consuming the data.

Furthermore you probably will want to decouple the service's data representation from the data model so that the clients won't be affected because you are constantly trying to keep the data representation synchronized with the data model. It's the service's job to do the mapping between the data model and the data representation.


The second approach (they prefer) is easier to consume because it does not take much logic to translate the response.


That depends on the tools that you use. XPath is often used to extract just a portion of the data form. It would be much easier to address/query the data in the first representation. Also many tools can extract information they need from element content, fewer can make sense of element attributes. In JAXB it would be much easier to map <IncomeStatement> to an IncomeStatement object than it would be to map a <report type="IncomeStatement"> (especially its child elements).

I wonder if "the second approach is easier" because it (right now) "simply" requires some handcoding. However in the long run it may be more effective to use a code generation tool like JAXB to generate (un)marshalling code for you. With the second representation mapping with JAXB may require an additional manual step of creating a dedicated IncomeStatement object from some "generic" ReportRows container while the first representation could be mapped directly by JAXB to an IncomeStatement object - so the second representation could actually generate more manual work.


The other argument for the second selection has been that since the clients of our service know what an income statement is then they don't need structure.


Well, that means that the structure is implicit. If it is implicit it is not part of the contract. If it is not part of the contract somebody is bound to "forget" about some part of it. The first representation can be easily described and validated with XML Schema, the second cannot.
The XML Schema and xsd:any and xsd:anyType are the ultimate in "implicitly structured XML data" and have caused all sorts of trouble: Tip: xsd:any: A cautionary tale. It basically leads to incomplete contracts.


Now I have read books on SOA and I understand the value of putting a model on top of your service but can anyone help me explain this benefit in a more precise way?


SOA in Practice: The Art of Distributed System Design 15.5 Data types; page 204:
The more complex data types and programming models you introduce, the more tightly coupled the systems will be.

Harmonizing data types over distributed systems is a common and natural goal, because it simplifies data sharing. Be careful, though - once you have introduced a new fundamental type, you will probably never be able to get rid of it. Note:In one project, we defined the generic list for future technical data having a key, a value, a type of information for the value, and some additional hints on dealing with this value (e.g. one attribute allowed to define that service providers should pass this data through when they call other services while processing a service call).


Sound familiar?

The second representation is satisfactory if the service consumer attaches no semantic meaning to the data - e.g. it just requests a report by name ("IncomeStatement") and then blindly displays a two column table where the first column is the "label" and the second column is the "text". If however the differentiation between "NetSalesRevenue" and "CostOfGoodsSold" is in fact meaningful to the service consumer then the second representation lacks expressiveness.

Web services have become increasingly document-oriented in the support of distributed business processes - if the IncomeStatement carries any significance within the overall business process then it deserves its own document definition even if it is just for the sake of clarity.
[ January 15, 2008: Message edited by: Peer Reynders ]
 
It is sorta covered in the JavaRanch Style Guide.
 
subject: Well defined or generalized service contract?