Entity Translator

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

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 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.