Chapter 7. Iteration 3: Consuming the Pattern
We pick up with the next iteration of the project. At this point Jordan has built, tested, and published the Subsystem Façade pattern.
In this iteration we transition to pattern consumption, where the focus will be on acquiring and using the Subsystem Façade pattern. Rajesh and his team will use the completed pattern implementation to work on the User Management subsystem, and John’s team will use it to refactor the Items Management subsystem. Duncan will not be involved in this effort, so the team will get to see if the pattern truly captures his expertise.
Figure 7.1 shows the main PBE activities in this iteration.
Figure 7.1. Main PBE activities performed in this iteration
In this iteration we will focus on three main scenarios. The first two scenarios are closely related as they both pertain to applying the pattern; however, they differ in terms of the underlying target. In one scenario we look to apply the model where no code for the subsystem has yet been created. In the second scenario we examine a situation where the code for a subsystem already exists and the team plans to refactor to the pattern. The third scenario in this iteration is related to providing feedback and capturing metrics, both of which serve as important inputs to future pattern activity.
Launching the Iteration
Like the other iterations, this iteration starts with Michael leading a team meeting to define the goals and content of the iteration.
John’s team and Rajesh’s team are driving the effort in this iteration. John’s team will take responsibility for the Items Management subsystem, and Rajesh’s team will take ownership of the User Management subsystem.
For this iteration the goal for John’s team is to finish the implementation of the Put Item Up for Auction use case as well as implement the Remove Item from Auction use case. One additional task for them as they take ownership of the Items Management subsystem is to refactor it to match the Subsystem Façade pattern. In particular, if modifications are made to the pattern implementation, applying the changes to the Items Management subsystem will be quick and painless. Using the pattern implementation also ensures that all of the subsystems are consistent in their adherence to the pattern.
Rajesh’s team will start building the User Management subsystem by implementing the Log In and Create Account use cases.
Duncan will not be involved in John’s and Rajesh’s efforts. He will focus on the Start Auction and Close Auction use cases. So the organization will see how successful they have been in leveraging his expertise.
With the Subsystem Façade pattern complete, Jordan will start working on the Test Data Reset pattern, which was identified earlier as a candidate pattern (Chapter 4). Recall that this pattern will be important in helping the team to test the LogoAuction application as it makes its way through different environments such as development, testing, and so on.
Using the Pattern in a New Subsystem
In this iteration Rajesh’s team is scheduled to work on the User Management subsystem. As they embark on the effort, Rajesh reminds the team that they need to think in terms of finding and using patterns where it makes sense.
Sandhip recalls hearing that a new pattern is available to help with subsystems and, following the Use an Asset Repository guideline (Chapter 16), turns to the asset repository to find the pattern. He accesses the repository and searches using subsystem as his keyword and indicates that he is searching for assets tagged pattern. The repository returns the Subsystem Façade pattern, which sounds familiar. He sees that there are two related assets:
• Pattern specification
• Pattern documentation
He reviews the details for the pattern and the related assets and then proceeds to download all three. He then reviews the pattern specification to gain a better understanding of the pattern. Rajesh’s team, while skilled in a number of areas, does not have anyone with Duncan’s skills in Java EE. They view the pattern as a great way to be able to leverage Duncan’s expertise without having to compete for his time (or deal with remote collaboration challenges).
Installing the Pattern Implementation
With the pattern implementation now in hand, Sandhip reviews the documentation to understand how to install it. The pattern implementation and the associated profile are packaged within a feature, so he quickly and easily installs the pattern into Rational Software Architect.
Once it is installed, Sandhip reviews the pattern’s documentation, which is embedded within RSA (recall that Jordan followed the Embedded Pattern Implementation Guidance pattern; see Chapter 14). He notices that a number of supporting artifacts are installed as well, including a sample input model. He follows the documentation to set up a project, add the sample input model, and test the application of the pattern. Everything works as expected, and Sandhip is confident that the pattern has been installed correctly.
Applying the Pattern to the User Management Subsystem
In the pattern implementation’s documentation Sandhip sees Figure 7.2, which shows the roles to which he needs to assign elements.
Figure 7.2. Subsystem Façade roles
The pattern has two roles, Subsystem and Datasource. However, Datasource is preconfigured, so Sandhip has to focus only on the Subsystem role.
Sandhip accesses the SCM repository and adds the domain model to his workspace. Figure 7.3 shows the domain model entities owned by the Users subsystem. These are all the entities that the pattern implementation will generate for him; the only thing he has to do is configure the pattern to focus on this subsystem and then apply the pattern.
Figure 7.3. Users subsystem entities
The first thing that strikes him is the inheritance relationship associated with the Role entity. Sandhip knows that class inheritance can be mapped using different strategies and is curious about how the pattern will handle the situation. He checks the documentation, focusing on the overview shown in Figure 7.4, and finds that the Class Table Inheritance pattern is used. He makes a note to spend some time reading about the Class Table Inheritance pattern to grow his skills in this area.
Figure 7.4. Overview of the patterns that are encapsulated in the Subsystem Façade pattern
He then creates the transformation configuration for applying the Subsystem Façade pattern to the Users package in the domain model. Running the transformation generates the Java EE projects as shown in Figure 7.5.
Figure 7.5. UserManagement entities and the generated projects
Sandhip wants to ensure that it is clear that the pattern is being used, as well as how it is being used. Others on his team will need to understand the usage and its impact on the application. Requirements may change or defects be found once the application is in development. Sandhip follows the Communicate Design with Patterns guideline (Chapter 16). In this case he is using a pattern implementation that allows him to cross levels of abstraction, transitioning from a UML model to a set of text-based artifacts. The tool, by default, has a transformation configuration file to denote the mapping, but he’d like something a little more visual. To that end, he creates a new model that he uses to document patterns that are used across models. He creates a diagram, as shown in Figure 7.6, to denote the use of the pattern and the input and output artifacts.
Figure 7.6. Overview of instantiation of the Subsystem Façade pattern
Providing Feedback on the Pattern
The last step that Sandhip needs to do is to provide feedback on the pattern. Overall the feedback he provides is positive, as the use of the pattern simplified the work that he had to do. However, it would have been helpful if the business operation signatures were also automatically generated by the pattern implementation. He adds a feature request noting the need for this additional functionality and the value such an enhancement would add to the pattern. In addition, he’s heard that there may be a need to support SOA service requests from the subsystems and wonders if it would be possible to have the pattern implementation also generate the web services to support such functionality. He details a feature request for this functionality as well.
He also captures metrics related to his use of the pattern. Finding and downloading the pattern took only a few minutes. He then invested 2 hours in reading the documentation, installing the pattern, and testing the pattern. After that, he spent another 30 minutes applying and running the pattern. Overall, he spent approximately 2.5 hours on finding and using the pattern, the majority of that time on familiarizing himself with it.
Refactor the Items Management Subsystem to the Pattern
During a team meeting, John hears that the Subsystem Façade pattern implementation has been published. He also recalls that the Items Management subsystem serves as the genesis of the pattern’s exemplar. However, he is concerned about divergence between the subsystem and the pattern; in particular, what will happen as the pattern evolves over time? How will the two remain synchronized? John quickly confers with Duncan, and they decide that the best path forward is to refactor the Items Management subsystem by using the pattern implementation.
John’s first step is to search and retrieve the pattern implementation in the same manner as Sandhip. Once the pattern is found and installed, John spends time reviewing the documentation, particularly the section that explains reapplying the pattern. He focuses on the support for the “user region” tag that is mentioned as a way to preserve manually inserted code. The documentation states that manually added code should be inserted only between // BEGIN and // END lines. He also notices that user regions exist only in the generated façade classes (the session façade and its remote interface) as well as in the JUnit tests.
The next step for John is to test the application of the pattern to the Items Management subsystem. The goal is to see an example of what is generated and further understand the user regions. He applies the pattern in a new workspace, ensuring that he does not impact the actual code base with his test.
After the pattern has generated the subsystem, John starts looking at the ItemsFacadeInterface.java class, shown in Listing 7.1, to identify how and where the user regions // BEGIN and // END are used.
Listing 7.1. Excerpt of ItemsFacadeInterface.java
package itemsmanagement.facade;
// BEGIN user-region 01
/*
* Add your custom imports BEGIN and END tags
*/
// END user-region 01
import itemsmanagement.entities.Item;
import itemsmanagement.entities.Category;
import itemsmanagement.entities.Catalog;
import javax.persistence.PersistenceException;
import java.util.List;
public interface ItemsFacadeInterface {
public Item getItem(long itemid)
throws PersistenceException;
public List<Item> getAllItems()
throws PersistenceException;
public Category getCategory(long categoryid)
throws PersistenceException;
public List<Category> getAllCategorys()
throws PersistenceException;
public Catalog getCatalog(long catalogid)
throws PersistenceException;
public List<Catalog> getAllCatalogs()
throws PersistenceException;
// BEGIN user-region 02
/*
* Add your business methods between the BEGIN and END comments
*/
// END user-region 02
}
In the file he sees that there are two such sections, one for the custom imports and one for the operations exposed by the façade. He also reviews the ItemsFacade.java file and confirms that it is the same. Looking at the tests, he reviews the ItemTest.java and ItemsFacadeTest.java files. The import user region is still there, but the other user region is at the end of the files to allow for adding new tests.
Now that he knows where to add the user region tags to the actual code base, he can start the refactoring. From past experience in other projects he knows that a successful refactoring always includes tests to ensure that the refactoring does not break anything. Luckily, unit tests already exist and are contained in the ItemsManagementTests project. He can also reuse the web page that was developed to support the Put Item Up for Auction use case as a functional test.
He decides to start with the façade and its interface. He compares the interface of the actual project with the one generated by the pattern implementation. He notices that there is only one operation, addItemToAuction(), that needs to be handled. He checks the imports and notices that no action is needed, so he adds the //BEGIN and //END tags around the operation signature in the ItemsFacadeInterface.java file inside the ItemsManagement project, as shown in bold in Listing 7.2.
Listing 7.2. ItemsFacadeInterface.java with the Added Operation Signature
package itemsmanagement.facade;
// BEGIN user-region 01
/*
* Add your custom imports BEGIN and END tags
*/
// END user-region 01
import itemsmanagement.entities.Item;
import javax.persistence.PersistenceException;
import itemsmanagement.entities.Category;
import itemsmanagement.entities.Catalog;
import java.util.List;
public interface ItemsFacadeInterface {
public Item getItem(long itemid)
throws PersistenceException;
public List<Item> getAllItems()
throws PersistenceException;
public Category getCategory(long categoryid)
throws PersistenceException;
public List<Category> getAllCategorys()
throws PersistenceException;
public Catalog getCatalog(long catalogid)
throws PersistenceException;
public List<Catalog> getAllCatalogs()
throws PersistenceException;
// BEGIN user-region 02
public void addItemAuction( String name, String description,
Category category, byte[] image )
throws PersistenceException;
// END user-region 02
}
He repeats the operation to add the implementation of the method into the ItemsFacade.java file. He then runs the pattern implementation again and validates that the code he added has not been modified or deleted.
He can now go to the next step and validate that the modified code passes the unit tests. To do that he copies the interface and its implementation from the test project to the original project and runs the unit tests. All the unit tests pass, so he can now repeat this approach for the rest of the subsystem. When the original project is updated and tested, he commits the changes to the SCM system.
With success confirmed, John notifies the other team members that they should refresh their ItemsManagement and ItemsManagementTest projects to pick up his changes.
Summary
In this iteration we focused on how the Subsystem Façade pattern was consumed by the Oslec team. Figure 7.7 shows the main PBE elements we have covered in this final iteration.
Figure 7.7. Summary of PBE elements covered in this iteration
This wraps up the case study discussion. We went through a few iterations of the project, looking at how the team can adopt PBE and succeed in using it. Their efforts have resulted in the identification of a number of candidate patterns, and then the selection and creation of one of those candidate patterns, the Subsystem Façade pattern. We saw how Alex put thought into and leveraged metrics and ROI as a basis for deciding what pattern to create.
An interesting aspect of the Subsystem Façade pattern implementation is that as the team worked on this pattern, they found and then leveraged a number of related patterns. They were able to encapsulate those patterns, providing the user of the pattern with a simplified experience.
As we’ve gone through the case study, we’ve looked at using pattern specifications as an alternative to pattern implementation as well as a complement. There are times when an implementation would not be worthwhile to create; yet we still need to incorporate a best-practice solution. We also looked at using a pattern specification to help Pattern Users understand the details that are captured in a pattern implementation.
We’ve also seen some of the ways patterns can be shared with others, supporting reuse of the pattern, where the reuse could be a straightforward application of the pattern or a means to guide a refactoring effort.