CSC/ECE 517 Spring 2013/OSS M604

OpenMRS Change Patient Relationships

README

The design document for the project can be found at [1]

The project is currently hosted at a long term VCL image found at [2]

The code for our module is hosted on github at [3]

The module's github readme file can be seen at [4]

To Use:

1. Login with user:Admin password:Admin123.
2. Click the 'Administration' button in the top-right corner.
3. In the bottom-right corner, under 'patients' there should be a link for "change patient relationships".
4. Click on the 'change patient relationships' link
5. The content of the change patient relationships module should be displayed.

To see a list of possible patients, it may be useful to open a separate tab with the 'Find/Create Patient" menu from the main menu bar.

Writing Exercise 2

Design Overview of the Module

OpenMRS modules utilize a modified Spring MVC framework [5]. The skeleton for the module is first generated using convenient maven[6] artifacts provided here [7].

The 'change patient relationships' module utilizes 5 basic files.

1. The main page is a .jsp [8] page, the code can be found at [9].
2. This .jsp page is linked to a spring annotated controller [10], the code can be found at [11]. The annotated controller maps the manage.jsp form actions using the '@RequestMapping' annotations. This pattern can be observed by viewing the manage.jsp code and comparing the <form> tags to the @RequestMapping annotations in the java code.
4. The controller along with the spring framework link the form actions from the 'manage.jsp' page to java objects defined in the following .java files. [12] and [13]
5. The module utilizes OpenMRS's services infrastructure to create services with the following code [14]. The services found within this class are retrieved from the OpenMRS context object inside of the above controller code (#2). The ChangePatientRelationshipsServiceImpl.java class utilizes OpenMRS database APIs [15] to actually change the patient data in the OpenMRS database.

The entire module is packaged in an OpenMRS .omod file using maven and pre-created packaging scripts. The .omod file can be found here [16] and installed into any OpenMRS server using the 'Administration'>Manage modules page.

Object-Oriented Design Principles

Encapsulation
There were several instances of encapsulation used through out our implementation code in the OpenMRS module. For example, to get access to relationships between people in the database in OpenMRS, we first had to use the Context class to get a PersonService object type and then use that object type to access a list of relationships:

personService = Context.getPersonService();

Here, getPersonService() is a static method in class Context that doesn't require instantiating a Context object to call the method. getPersonService() can be directly used as a class method without having to know the details of how the method has been implemented and designed.
Another example is making helper methods and instance variables private.

private Person getPersonOut(List<Relationship> relationshipList, String nameOut)

This is a helper method to the changePatientRelationships() method that helps locate the Person object for updating the patient relationship. As it is not directly used in the manage.jsp page for the user-interface, it is made private to restrict access to it.

private ChangeRelationshipsDAO dao;
private List<Person> people;
private List<Relationship> allRelatedPeople;
private List<RelationshipType> existingRelationshipTypes;
private int noOfRelatedPeople;

These instance variables are also made private in our module class to prevent the potential corruption of data if they were to be accessed publicly.

Open-Closed Principle
In the OpenMRS module, existing classes that had already been tested were not modified, which exemplifies the open-closed principle [17]. This module is an extension of the OpenMRS functionality. Our ChangeRelationshipsServiceImpl class is an added class to specifically add the functionality of being able to update the relationships of several patients at one time. Specifically, in our the ChangeRelationshipServiceImpl, we extend the class BaseOpenmrsService to implement the new functionality:

public class ChangeRelationshipsServiceImpl extends BaseOpenmrsService implements ChangeRelationshipsService

Design Patterns

Quite a few design patterns were used to design this module.

Model View Controller

As there was significant UI and Database functionality, the use of MVC was inevitable MVC The class ChangeRelationshipServiceImpl corresponds to the model. This class contains the functions to fire queries to the database and also insert new records/update existing records. Following is the code snippet for the class

public class ChangeRelationshipsServiceImpl extends BaseOpenmrsService implements ChangeRelationshipsService {

public Person getPersonObjectFromInputname(String fromPerson) {
/*Matches the input string to an existing person object and returns the first person*/
}

public RelationshipType findRelationshipTypeFromInput(String relation) {
/*Matches the input string to an existing relationship type*/
}

public int numberOfRelationships(Person fromPerson, RelationshipType fromPersonRelationship) {
/*Function returns the number of people who are related to fromPerson as a fromPersonRelationshiptype */
}

public int numberOfRelationships(Person fromPerson) {
 /*Function returns the number of people who are related to fromPerson in any way */
}

public boolean updateRelativesToNewPerson(Person toPerson, RelationshipType toRelationshipType){
/*Updates relations of all relatives of old person to new toRelationshipType of toPerson. If unable to update the records of any of the       
relatives, the failure message is logged and the rest of the records are updated*/
}

The class ChangeRelationshipsManageController is the controller. This class contains the functions and attributes required for the view and also acts as an interface between the model and view. Code snippet for this class follows

public void manage(ModelMap model) {
/*Function to render the view and add attributes that are accessible in the view*/
}

public String checkPatients(){
/*Function accepts string input of name of person and relationship type and maps it to function in the model that returns the number of  
related people*/
}

public String updateRecord(){
/*Function accepts string input of name of new person and new relationship type and maps it to the function in the model that updates the  
records to reflect the relationships*/
}

The file manage.jsp is responsible for the view and contains 2 forms. One to search for all the related people and the other to confirm the changes that have to be made with respect to the new person/new relationshiptype or both

Front Controller Pattern

Similar to the MVC pattern, the Front Controller Pattern provides a centralized entry point for handling requests.[2] The class ChangeRelationshipsManageController (link to source code above) demonstrates this design pattern. As all the requests from the manage page are mapped onto functions in this page, this class is the centralized controller in the design.

Iterator

Iterator is a behavioral design pattern used to implement accessing elements of a list quite frequently in the code. A code snippet example would be

for(Relationship relationship : allRelatedPeople)
{
if(toPerson.equals(relationship.getPersonB()))	
{
areAllUpdatesSuccessful = false;		//as Person1 related to Person1, so avoid by skipping. Boundary case.
myLogger.print("Unable to update record for " + toPerson);
continue;
}
relationship.setPersonA(toPerson);
relationship.setRelationshipType(toRelationshipType);
personService.saveRelationship(relationship);
}

Strategy

Although, this pattern is not a strong contender for a design pattern used for this code, the Strategy Pattern does show itself in the controller function checkPatients()

public String checkPatients(@ModelAttribute("patientSearch") PatientSearch patientSearch){
if(fromPersonRelation.equals("All"))	//in case all relations of a person have to be changed call 
{					// a different overloaded function 
noOfRelations = changeRelationshipService.numberOfRelationships(fromPersonObject);
}
else
{
RelationshipType fromPersonOldRelationshipTypeObject = 
changeRelationshipService.findRelationshipTypeFromInput(fromPersonRelation);
noOfRelations = changeRelationshipService.numberOfRelationships(fromPersonObject, 
fromPersonOldRelationshipTypeObject);
}
}

Depending on the input relationship type selected, two different functions are used to find all the related people. There may not a be a significantly different algorithm used to find the result, but at the database layer, the queries are different.

Testing

The framework used here for testing is JUnit4 All the code for the test functions are at ChangeRelationshipsServiceTest.java

The test class consists of simple unit tests to test the working of each function used in the ChangeRelationshipService class.

Setup()

The setup() function is the one responsible for setting up the background before testing all the functions. It initializes all the objects used for testing later. The code for setup() is as

Test Data

The createTestPeopleAndRelations() functions is similar to the setup function, as it too sets up the background data required for some of the testing, but since not all of the unit tests require a sample data, they are in a separate function and only those functions that require the data call them. Code snippet for the function :

Similarly the function deleteDataCreatedForTests() is a cleanup function that removes all the data created specifically for the tests. Code snippet for the function :

The functions createNewRelationType() and createAndSavePerson() are helper functions for the test data setup functions mentioned above. The createAndSavePerson() saves each person to the database while the createNewRelationType() function saves each new relationship type tothe database

Unit test : shouldSetupContext() and shouldSetupPersonService()

Makes sure that the service objects are initialized and not null.

Unit test : getPersonObjectFromInputnameTest

Asserts that the function getPersonObjectFromInputname() returns exactly one person in case a record matching the given name is found, else returns a record not found error

Unit test : findRelationshipTypeFromInputTest()

Asserts that the function findRelationshipTypeFromInputTest() returns the relationship type in case a record matching the given type name is found, else returns a record not found error.

unit Test : numberOfRelationshipGivenPersonAndRelationshipTypeTest()

Tests wether the function numberOfRelationships() returns the right number of related people given the name of a person and the relationship type.

unit Test : numberOfRelationshipsWhenAllSelected()

In case the user chose to change all the relationships for a given person, this test case checks to see if the function numberOfRelationships() returns the right number of people related to the given person in any possible way.

References

[1] Model View Controller [2] Front Controller Pattern [3] Iterator