David Bau has written a very nice column on Encapsulation versus Representation. He walks us through a project where "Several engineers are building a complicated software system together, and naturally, they are trying to figure out how to divide the work up". They could choose Encapsulation, and agree upon the behaviour, or they could choose Representation, and agree upon the data.

As David walks us through the example he shows you that both Java and XML have their uses in designing the application.

He does this by showing both choices with respect to an order management system.

First we see Order Management by Encapsulation:

Here the work is divided up by encapsulating the behaviour of an "order" via a formal interface:

    interface Order
    {
         show(); // present the order to the user for editing
         submit(); // send the order in for execution
         close(); // close out an executed order
    }

Then we see: Order Management by Representation

Here we divide up the work by representing an "order" as a formal data format, and then leave it up to the different engineers to build systems that exchange that data for whatever purpose they choose.

   <order>
     <customer>12345</customer> <!-- must be a valid 5-digit ID-->
     <date>2003-11-26</date> <!-- date of the request -->
     <request>Change oil, check tires</request> <!-- the request -->
     <estimate>45.00</estimate> <!-- estimated charge -->
     <assigned>Jim</assigned> <!-- employee -->
     <charge>450.00</charge> <!-- actual charge -->
   </order>
   
Choosing Between Encapsulation and Representation
   
"Which model should be chosen for our order-entry system? It is a business decision. Each approach has strengths and weaknesses. Here is the choice facing the owners of our car-repair shop:
   
If it is important for you to keep your current computer applications, but you want to free yourself to let your applications be capable of working with new kinds of data - as Dixies has done by adapting their existing business process to a new kind of business - then what you want is program encapsulation.
On the other hand, if it is important for you to keep your current data, but you want to fee yourself to use your data in new applications in the future - as Wal-Mart has done by finding new business techinques to utilize their cash register receipts - then what you want is data representation."

How does this work in the abstract?

Encapsulation:
1. Use encapsulation when your program outlasts your data.
2. Use encapsulation to subdivide tightly-coupled components of a system.

Representation:
1. Use representation when your data outlasts your program.
2. Use representation to connect loosely-coupled systems together.

Why do we care? David puts it well:

"Why is this all relevant? Because it gets behind the whole architecture of XML versus Java. The world is organized into many individual systems written in object-oriented programs like Java, exchanging data-oriented messages in formats like XML."

Read David Bau's entry: Encapsulation or Representation

Use encapsulation within a subsystem. Use representation
between subsystems.

Hmm, I don't see why a choice between the two must be made. We can't abstract on the data if we abstract on the process and vice-versa?!?! This sounds like, to make a software system, we can choose to use data or to write a program ;)

The two "approaches" seem completely orthogonal to me. Dealing with commonality and variability in data and/or program are two different, even though intertwined problems. Isn't there some confusion here between levels (layers) and aspects (in the general sense of the word, not the technical AOP sense) of the system.

Boris

http://www.jsfrepository.com - The JavaServer Faces Community
http://www.kobrix.com

Encapsulation creates a language API binding. This is the least
flexible option when trying to integrate between subsystems.
CORBA, RMI, RPC, etc have all pretty much failed for system
integration for this reason.

For example, i want to use Perforce via a programmatic interface.
They have a C++ API that runs on platform X. I use perl and i am
on platform Y. Within Perforce they should use a carefully
crafted encapsulation. If they had used SOAP or simple HTTP
at the subsystem boundry i would be set. These are available to me
in every language on every platform.

Encapsulation makes for a great internal program architecture.
Representation between subsystems makes for great accessibility
from any language and platform.

Perforce also has a data representation in the text format of the output of their command line client and I'd venture a guess that more people integrate with Perforce using this text representation than via the API (although I'd love to see a nice Java API).

I do use p4 and parse it the output. I would much prefer
a http or SOAP interface. Calling a program and parsing the
output is quite crude. Just love using those regular expressions
to extract if a file is in edit, integrate, etc.

> flexible option when trying to integrate between subsystems.
...
> For example, i want to use Perforce via a programmatic interface.
> They have a C++ API that runs on platform X. I use perl and i am
> on platform Y. Within Perforce they should use a carefully
> crafted encapsulation. If they had used SOAP or simple HTTP
> at the subsystem boundry i would be set. These are available to me
> in every language on every platform.
...
> Encapsulation makes for a great internal program architecture.
> Representation between subsystems makes for great accessibility
> from any language and platform.

Well said! Your example resonates with the thinking that went into the design of my project, OpenParachute.

By default, OP uses XML over HTTP to transfer representations of Java objects that are managed by the server. The XML representations can be manipulated and transferred back to the server for persistence (the server coverts the XML back into a Java object and persists the object, not the XML).

All operations are HTTP operations: HEAD, GET, PUT, POST, and DELETE.

Java clients can either use the XML representation directly or use the built-in converter to recreate the Java object from the XML representation, bringing the benefits of encapsulation. For example, your object may have methods that would only be meaningful within a given subsystem in your application, such as a method to display a GUI or process a command. Applications based on OP have the Representation style as the base, and can use (or not use) the Encapsulation style as they see fit.

Currently, there is no facility to invoke methods on objects on the server, only on objects in the client's process space. Invoking methods in a standard way over HTTP will be in the next major release -- this would be consistent with "great accessibility from any language and platform" and allow other clients access to what would normally be Encapsulated methods.

Boris,

That's a correct observation, the two concepts are in fact orthogonal and here's the explanation:

http://www.manageability.org/blog/stuff/encapsulation-or-representation

Carlos

They are orthogonal. You can use them both together or
independently. That's not very helpful though. As an engineer
you need to know the strengths and weaknesses of each
and how best to use them. Saying something is orthogonal
doesn't end a discussion, it begins it. The choice is
about how to layer and the implication to your architecture
and for those that use it.

thoff thoff,

First thing you need to explain is how they are othogonal. Simply stating it isn't helpful since from the point of view of the original author, they belong seem to belong to the same axis (i.e. not orthogonal).

So maybe you can kindly explain why it's orthogonal or are you just parroting what others are saying?

Carlos

I didn't just state it. The next sentence says why.
They are independent of each other. One does not rely
on the other. They are well separated. One is irrelevant
to the other. Orthogonality is always along a particular
relation though. In another relation, say implementing
a system, the are not orthogonal because they are solutions
to the same problem, which makes them related.

thofff thoff,

"They are independent of each other. One does not rely
on the other. They are well separated. One is irrelevant
to the other. Orthogonality is always along a particular
relation though. In another relation, say implementing
a system, the are not orthogonal because they are solutions
to the same problem, which makes them related."


All you've just done is provide a definition of orthogonal.

You did not explain why ecapsulation and representation are orthogonal. To do this you have to define the axis were it is the case. That's not as simple as it seems.

Carlos

I believe i have shown they orthogonal. If one can't use
the definition of something to show if something meets
the definition then i am at a loss. They do not depend
on each other in any observable way. The fact that one
can be implemented without the other is sufficient proof
for me. Now we can quibble about what are the meanings
of fact, proof, implement, without, etc

My feeling is nothing i could say would now meet with
your approval giving our previous "conversation."

Insert here several more posts along these lines.
Then I'll reference a URL that purports to answer all
questions but does not. Next we are done.

Carlos,

Thanks for the explanation ;)

Boris

I would have prefered other terms. There's much confusion already.

http://www.dbpd.com/vault/9809date.html

"Show me your flowchart and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won't usually need your flowchart; it'll be obvious."

- Fred Brooks, The Mythical Man-Month

Br - J

Answer: Use oranges for juice and apples for a pie

I believe you can hide representation with encapsulation:

OrderSerializer
{
   void serialize(Outputstream out, Order o);
   Order deserialize(InputStream in, Order o);
}

So in this situation all application pieses can use unified API. Of course when there is need to communicate between subsystems or systems written in other language then representation make sense.

Interesting thoughts...

However, I wonder if the subject shouldn't read instead "data(base) modeling or object modeling"...

my 2 cts

The choice of words is confuses me but hopefully I got the gist of the post.

I think two important factors missed in the post are granularity and organisational or system boundaries.

I prefer to use encapsulation for most low granularity, intrasystem activities. However when discussing the APIs for inter-application, inter-system or inter-business-unit scenarios, the ability to interoperate with diverse internal schemas becomes important. It is in these scenarios that the schema for the data exchanged should be standardised/agreed upon. It is in these scenarios that representation complements encapsulation since the encapsulated data structures can continue be a little different than those represented in the agreement.

This case is somewhat similar to a scenario where one might prefer to use remote APIs (RPC/EJB calls etc.) for most intra application communication but choose to use a web service for inter application communication.

Dhananjay

Dhananjay,

That's correct the terminology used is a bit ambiguous.

Encapsulation was used in the sense of polymorphic interface.

Representation was used in the sense of schema definition.

However the concept of loose coupling encompases other relations, in particular granularity of message, sychronicity, number of verbs and so forth. See http://www.manageability.org/blog/archive/20030628%23principles_of_loosely_coupled_api/view

I believe the author may have omitted the fact that for two systems to interoperate in representation they have to agree on some standard. Preferably that standard is not implicit. That is it is in the form of a XML Schema or something like Schematron (i.e. Pattern based).

On second reading, the author actually fails to make the argument that representation is better for loosely coupled systems. If the schema in one system changes, doesn't it not affect the code in the other system?

Carlos

When I first read the piece I thought it was decent.

However, after more analysis, I realized that it's actually extremely terrible.

Oh Well!

Carlos

Carlos asks "If the schema in one system changes, doesn't it .. affect the code in the other system?"

Changing schemas and changing interfaces is a different topic that isn't covered in my article. I hope in my weblog to dive into a lot of detail in changing schemas in particular. It is a topic that is not widely understood as well as it needs to be.

The point of the article is to observe that "if you lay down unchanging interfaces you get X" and "if you lay down unchanging schemas you get Y". In the real world, of course, you aren't really stuck with X or Y because you actually can evolve your interfaces and change your schemas. But by laying down interfaces and schemas, you do incur higher costs for changing them, and if you cannot afford those costs, you do get X or Y.

It will take more articles to discuss the real world of changing interfaces and schemas, so Carlos is right, more discussion is needed. A short followup to some of the discussion has been posted at http://davidbau.com/

I have been enjoying the discussion!

David,

> Changing schemas and changing interfaces is a different topic that isn't covered in my article. I hope in my weblog to dive into a lot of detail in changing schemas in particular. It is a topic that is not widely understood as well as it needs to be.

Shall certainly look forward to that.

> It will take more articles to discuss the real world of changing interfaces and schemas, so Carlos is right, more discussion is needed. A short followup to some of the discussion has been posted at http://davidbau.com/

I read up that and respond based on it as well. You've looked at value objects as the sample and treated them as the base for a discussion for representation vs. encapsulation. Now value objects' <emphasis> primary </emphasis> intention is to address network latency issues. Value objects should be a little bit independently flexible of the underlying data structures <emphasis> when </emphasis> they are likely to be a part of the "representation contract". My personal choice in such scenarios has been to create "mappers" which map data between value objects and the internal business objects. The issue at hand is not of top-down or bottom-up, but of flexibility at either end while continuing with interoperability. I am no longer certain what is the point you are trying to make.

Dhananjay

Dhananjay - you are quite right. Value objects are typically introduced for performance reasons, not for interoperability reasons, and I've added a note to that article to acknowledge your point. I hope the choice of an example doesn't detract too much from the main message of the second article, which is:

1. Coarse-grained interoperability is served best with contracts that are just representations such as XML with XML Schema rather than encapsulations such as Java (or RPC) interfaces.
2. Representations are strongest when they are completely free of context and semantics, as exemplified by document file formats, HTML as contrasted with Memex pages, or (and this may not be the best example) value objects with no behavioral methods.

Being free of semantics is one of the underlying points that supports an article (a quite different kind of article) that begins a technical discussion of compatibility of versions of representations, which I've posted at http://davidbau.com/archives/2003/12/01/theory_of_compatibility_part_1.html

David

David,

You say:

>
> The point of the article is to observe that "if you lay down unchanging interfaces you get X" and "if you lay down unchanging schemas you get Y". In the real world, of course, you aren't really stuck with X or Y because you actually can evolve your interfaces and change your schemas. But by laying down interfaces and schemas, you do incur higher costs for changing them, and if you cannot afford those costs, you do get X or Y.
>

If that was the only point of your article, then point taken ;) However, you are talking about choosing between "using representation" and "using encapsulation". I think now I understand that what you meant in fact was choosing between "spending more time working on data representation" and "spending more time working on encapsulation/behavioral abstraction". Read that why, your article makes sense. Otherwise, it seems very confusing.

Or I am missing some deep insight implied by your comments. Then I would very much like to be enlightened.

Best,
Boris

http://www.jsfrepository.com - The JavaServer Faces Community
http://www.kobrix.com