Entity Translator

11/07/2011 • 6 minutes to read

In this article
Context
Problem
Forces
Solution
Participants
Process
Resulting Context
Example
Related Patterns
Acknowledgments

Retired Content

The Web Service Software Factory is now maintained by the community and can be found on the
Service Factory site.

This content is outdated and is no longer being maintained. It is provided as a courtesy for
individuals who are still using these technologies.
This page may contain URLs that were valid when originally published, but now link to sites or
pages that no longer exist.

Retired: November 2011

Context
A distributed application sends and receives messages with remote agents. The request
and response messages being transferred exist in code as classes and contain serialization
rules for their state between network nodes.

Within the business logic tier, a domain model exists that contains classes that represent
entities in the system. These classes may not contain serialization rules.

Problem
Problem
How do you transform entity objects from one type to another?

Forces
Any of the following conditions justifies using the solution described in this pattern:

A solution needs to interact with external business partners. The business

partners use a standardized data format that is different from the data models and
format used by the solution.
An application cannot be dependent on the data structure used by external
interfaces. The transformation of external types to internal types used by an
application causes a dependency that represents tight coupling. Any changes to data
structures used by the external interface would require changes in applications that
use the interface.
Serialization of request and response data. Business entities should not contain
information related serialization rules.
Changing an existing data model is not feasible. With an existing legacy data
structure in place, it is economically not feasible to change that structure to support
standard interfaces.

Solution
Implement an entity translator that transforms message data types to business types for
requests and reverses the transformation for responses.

The entity translator is an object that is tightly coupled to message data types and business
entities, while providing loose coupling between the consumers of the types. In other
words, components of an application use the translator to transform data types and the
translator has no knowledge about operations provided by the application. This behavior
provides the ability to change data types on either end of the interaction without requiring
changes to the other end. The only component that needs to be updated is the translator
itself.

Participants
Entity translation involves the following participants:

Business entity. This is a class used to represent a domain model entity within the
 business tier of an application.
Data contract. This represents a data structure used by the service interface.
Service interface. The service interface provides operations that use data contracts
for request and response messages.
Entity translator. The translator is responsible for converting between data contracts
and business entities.
Transaction script. This is a class that processes incoming requests from the service
interface and, if necessary, returns a response.

The diagram in Figure 1 identifies the relationship between participants in this pattern.

Figure 1
Relationship between participants in the Entity Translator pattern

Process
Entity translation consists of the following high-level tasks:

Incoming data contracts are translated into a business entity. The entity translator
creates an instance of the business entity and initializes it with data from one or more
data contracts.
Outgoing business entities are translated into a data contract. The entity
translator creates an instance of the data contract and initializes it with data from one
or more business entities.

Data Contracts Are Translated into a Business Entity

To translate data contracts into business entities:

1. The entity translator provides a function that takes one or more data contract classes
as parameters and returns a specific business entity.
2. Within the implementation of the function, a new instance of the business entity is
created and initialized using data from the data contract classes.
3. After a new instance of the business entity has been initialized, it is returned to the
application that made the request.
Business Entities Are Translated into a Data Contract

To translate business entities into data contracts:

1. The business controller returning a response can use a function on the entity
translator that takes one or more business entities as parameters and returns a
specific data contract required by the service interface. This is accomplished by
creating an instance of the data contract and initializing it with data from the business
entities.
2. After the data contract is initialized, it will be sent to the service interface that made
the original request.

Resulting Context
This section describes some of the more significant benefits, liabilities, and security
considerations of using this pattern.

７ Note

The information in this section is not intended to be comprehensive. However, it does

discuss many of the issues that are most commonly encountered for this pattern.

Benefits

The benefits of using the Entity Translator pattern include the following:

An entity translator can be used to provide a transformation between new

standardized data structures and legacy data structures within an organization.
The use of an entity translator provides the ability to implement loose coupling
between different layers of an application. For instance, data contracts can be
modified without affecting a business tier, and business entities can be modified
without affecting a service interface.
The implementation of an object-based solution for data transformation is much
faster than using an external mapping file, such as XML, and generic translators that
use the mapping file.

Liabilities

The liabilities of sing the Entit Translator pattern incl de the follo ing:
The liabilities of using the Entity Translator pattern include the following:

Data can be lost between translations when translated data types do not support all
of the fields found in the original data types.
It may be necessary to call multiple translators during a single action, which can
increase complexity by requiring process dependencies on consumers of the
translator. This can be mitigated by using a process manager pattern.
Implementation of an object-based solution requires the creation of custom objects
that have to be maintained. As the number of data types increase, the maintenance
requirements of entity translators will also increase.

Security Considerations

To perform translations, the data must be deserialized and accessible. This requires that
any encrypted messages be decrypted before calling the translator.

Example
The service interface of a banking solution uses data contracts for input parameters and
return values for service actions. The business tier that provides an implementation for the
service interface uses business entities. To process requests in the business tier, data
contracts must be translated into business entities. Business entities included in a response
from the business tier have to be translated into data contracts.

The UML sequence diagram in Figure 2 illustrates the interaction of objects used to
implement an action that returns customer information:
Figure 2
Interaction of objects used to implement the Entity Translator pattern

The following steps describe the interaction between objects:

1. The service interface calls GetCustomer on the service implementation named

CustomerManager and passes it a requestID, which is defined as a DataContract
type (not shown).
2. The service calls CreateLoginID on the translator and passes it the requestID data
contract. The translator transforms the requestID data contract into a
BusinessEntity:LoginID type.
3. The service calls GetCustomerByLoginId on a transaction script object named
CustomerController and passes it the loginID business entity. The transaction
returns a BusinessEntity:Customer type
4. The service calls CreateServiceCustomer on the translator passing it the customer
business entity. The translator transforms the customer entity into a
DataContract:Customer type.
5. The customer data contract is returned to the service.

Related Patterns
The Entity Translator pattern is similar to the Message Translator pattern described in
Integration Patterns: Designing, Building, and Deploying Messaging Solutions by Gregor
Hohpe and Bobby Woolf.

Acknowledgments
Hohpe, Gregor, and Bobby Woolf. Integration Patterns: Designing, Building, and Deploying
Messaging Solutions. Addison-Wesley, 2004.