6 Adaptable Technology Wrapper

The sixth principle seeks to harmonize enterprise communication:
When aligning an API with a Pattern Language consider using adaptable technology wrappers to increase programming consistency regardless of technology choices.

Based on experience with “the Company,”[1] an “adaptable technology wrapper” (ATW) can: align the Application Programming Interfaces (API) of chosen technologies, provide pattern enforcement, limit API complexity via filtering, reduce duplicate code, assist with JUnit testing, and provide feedback of the runtime execution of a technology.

Perhaps the earliest widespread example of intentionally aligning an API with a pattern collection was provided by the Spring framework.  In the following @Repository Javadoc example, the alignment is made clear by stating the origin of the Repository pattern:[2]

@Target(value=TYPE)
@Retention(value=RUNTIME)
@Documented
@Component

public @interface Repository

Indicates that an annotated class is a "Repository", originally defined by Domain-Driven Design (Evans, 2003) as "a mechanism for encapsulating storage, retrieval, and search behavior which emulates a collection of objects."

A technology wrapper may be understood by analogy; instead of wrapping a single Java object (class) a technology wrapper normalizes an entire API. A PED technology wrapper aligns an API with our Unified Pattern Language.

Wrapper

This figure suggests an API Wrapper as analogous to a Java Object Wrapper.

In addition to pattern alignment, a creative wrapper author can implement modest pattern enforcement. For example, at “the Company” we have used a coding convention runtime exception if a concrete class name lacks the published suffix from the Unified Pattern Language. Here is an example enforcing the Domain Entity (DE) pattern suffix:

suffix

This figure displays jPED source for enforcing the DE suffix.

The 2013 version of Microsoft Word for Windows has 39,900 entries in the Help system. If you studied one of those entries per day it would take over 109 years to learn all the features of this one piece of software! Word is hardly unique; many technologies are feature-bloated beyond an ability to learn them quickly. An ATW can limit API complexity by filtering out seldom used features that don’t align with a the pattern language.

As an example, consider the following diagram listing the nine methods of the API for the JPA EntityManagerFactory class:[3]

EntityManagerFactory

This figure lists the API for the JPA EntityManagerFactory class.

There is an opportunity to reduce the number of public methods in this class. Presume that the design calls for the EntityManagerFactory to remain durable for the life of the application. In this case, there is no need to ever invoke the close() and isOpen() methods. This illustrates the point that by using a patterned approach an ATW can filter API verbosity.

Copy-and-paste is perhaps the most obvious practice yielding duplicate code. Another form of duplication derives from using boilerplate code.[4]  For example, two or more occurrences of boilerplate code may perform virtually identical functions while addressing different user stories.  Duplication is sometimes a response to the demands of a verbosity-inducing API.  That is, some APIs lack cohesion and thus impart this short-coming on an application; although the technology may be very useful.

The numerous tools and algorithms available for detection of duplicate—and wasteful—code attest to the widespread recognition of this hazard.[5]  We learned early on with Todd’s[6] team that by wrapping two new (new to “the Company”) technologies,[7] we could realize a significant reduction in source code operations required to implement and maintain boilerplate code.

It has been interesting to observe that as APIs become more powerful—powerful in that operations accomplish greater amounts of work—the application JUnit test code sometimes becomes more verbose! Tests requiring excessive operations (lines of code) constitute a test code “smell” indicative of an overlooked opportunity to make effective use of an ATW.

An ATW can include “assert” methods that dramatically ease JUnit test design and construction complexity in combination with the JUnit Strategy for Testing. This example enables asserting JSR-303 validations with a single line of test code.

Assert Validate

This figure displays a Justify convenience assert method for validations.

An ATW can also provide integrated logging as feedback from the runtime execution of native technologies. In recent years, some newer technologies such as JSF (with its Development Project Stage) have begun to incorporate using additional runtime logging as development feedback. The following code sample establishes four discrete modes that augment exception, performance, lifecycle, and trace logging:

Log Modes

This figure displays four discrete modes for declarative logging.

These logging modes enable explicit invocation for production and test code during development, continuous integration and production execution. Modern asynchronous logging enables verbosity without a performance penalty.

At least two additional benefits accrue to this principle of wrapping preferred technology APIs. One relates to software flexibility:

Wrapping third-party APIs is a best practice. When you wrap a third-party API, you minimize your dependencies upon it: You can choose to move to a different library in the future without much penalty. One final advantage of wrapping is that you aren't tied to a particular vendor’s API design choices. You can define an API that you feel comfortable with. (Feathers 2009, p. 109)

A second benefit can derive from decoupling a technology and its API: insulation from security vulnerabilities. As previously mentioned, in 2006 “the Company” began work on an ATW around Struts intended to enhance convenience and safety. In 2013, a Struts vulnerability was discovered and options for remediation subsequently emerged within the open source community. Because many teams had elected to use a Struts ATW, “the Company” was able to apply remediation for hundreds of developers across six continents with a simple JAR update.

References

[1] In 2002, Java was adopted as the standard platform for in-house development at a successful large automotive manufacturing enterprise (“the Company”).

[2] http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/stereotype/Repository.html

[3] http://docs.oracle.com/javaee/6/api/javax/persistence/EntityManagerFactory.html

[4] In computer programming, boilerplate code or boilerplate is the sections of code that have to be included in many places with little or no alteration.

[5] “Sonargraph-Explorer comes with a powerful duplicate code detection algorithm.” https://www.hello2morrow.com/products/sonargraph/explorer.

[6] Todd Hall was technical lead and architect for the original 2004 team launching the PED journey.

[7] In this case, Struts and Toplink.

Feathers, M. 2009. Error Handling, In R. C. Martin, ed., Clean Code. Pearson Education, Inc., 103–112