Flexing Your Code

Blistering Pace Development using: DDD, DI, AOP, AGILE and some CLEAN CODE

2010-07-09T11:44:00.000-07:00

I recently managed and jointly developed a system which evolved into the culmination of several methodologies and practices. We were severely short-staffed being a band of 3 and weren't the strongest technical team either.

Managing this group proved to be a challenge, and i had to pull out a few improvisations and tricks

to get the team to work together effectively and efficiently. Being a true techie at heart, management is the last thing i prefer to do, yet the team decided i should ... and i was dubbed.

We chose to follow the ICONIX process, which proved to fit in well with achieving a domain-driven-design.
More disciplined than XP and in some cases reminded me of my Waterfall experience. Yet very iterative in nature and yet we were able to produce a system at a blistering pace. Needless to say this post will be on my reflection on our technical achievements while understaffed and not on any particular process.
I'm convinced that a process is not a SILVER BULLET at all, in fact i believe a process should only facilitate the quest a team decides to undertake. I'ts like an adventure with Robin Hood or the Three Muskateers,
you decide which road to undertake, the process only facilitates to keep marble under your feet.

The first essential component to speeding up development was to understand the problem correctly.
Placing things into context and building a common understanding of the problem with your client was
the first requirement. Below is an excerpt from a write-up I recently made ... i added it since it captures
the gist of what i think a DDD should accomplish.

"In the pursuit of a proper solution for a problem, the problem to address needs
to be understood correctly and thoroughly. An incorrect comprehension of a
problem domain could degrade an otherwise elegant solution to become substandard.
Consequently, placing software requirements in context of the real
world is an essential exercise.
By expressing real world phenomena within a software application itself not
only aligns it closer to the needs and requirements of a client, but also assists
in the establishment of a ubiquitous language amongst different stake-holders.
A software construct not only communicates directly to a machine, but also
serves as a platform for communication amongst developers and future maintainers
of a system. A software construct that utilize a glossary build from an
established ubiquitous language would not only serve its purpose as an interface
between developer and machine, but also increase effective communication
between developer and client." - Michael (2010)

The second requirement to achieve blistering pace development was to establish
similar collaboration and mutual understanding amongst the team members. Sure
enough a DDD will assist, but more is required. A common understanding of high-level design and
architecture keeps everyone in the loop. We have vision, we all know where we're heading.
A visual representation of your vision whether it be an architectural view or a couple of robustness analysis
diagrams stimulates creativity ... put your PC aside ... to achieve a great design requires lateral thinking
and developers that are kept in the loop. A developer's feedback keeps everyone in touch of technical
feasibility and estimates (some design might be easy for us to implement, it does not however imply that the individual tasked with that design would find it easy... u need to put design in context of technical abilities).
A complex design might be highly modifiable and flexible, yet a simpler solution
could take far quicker and easier to accomplish technically. Yes we all know developers can give
management the moon, however that doesn't imply we'll have the moon ready for you next month !!
My answer, cut off what you can early on but don't neglect the domain. Whatever you do above all else,
KEEP YOUR DOMAIN LAYER UP TO DATE !!!
Tackling business complexity is highest priority, technical extensions are easy to add later on. Of course establishing a commonly understood technical language by naming new design patterns and old ones alike, assist in establishing a ubiquitous "techie" language.

The third requirement to achieve blistering pace was to streamline technicalities.
Infrastructure and interface code we've all written over and over and over again. Surely we can encapsulate that recurring pattern, it will save soooo much time. My answer to this is the culmination of frameworks, dependency injection and aspects. Choosing your framework is critical, don't fall into a trap hole.
Some frameworks give excellent speed-ups at first but severely limit flexibility later on.
IMHO a framework should provide support for some kind of DI though. Delegation and strategies are just so much easier to accomplish using DI, and the best part is that it keeps code clean, which of course is my next point.

Writing clean code is essential to increase maintainability and progress. A code base that is self explanatory is much easier to follow and extend than a mesh of spaghetti. By avoiding puddles of mud you save multitudes of wasted brain cycles trying to grasp context of surrounding code, and facilitate focus on expressions of system behaviour instead.
Aspects is an effective way to delineate boundaries and enforce code policies or conventions.
Why use static analysis tools in a continuous integration system while you could have prevented it @ code time using aspects instead ? Time savers like that and pragmatic approaches to solving difficult hurdles just help so much in the long run. Of course one should not neglect conventional tools and methodologies like continuous integration, test driven development, test \ production environments, effective development environments (IDE, screen multiplicity, pc performance, spreadsheet timers, build tools and so on etc. etc. etc. they all assist to speed up development bit-by-bit. Standardization on tools also help, but watch out not to stifle creativity in the process. Too much red tape is not a nice atmosphere to work in (well that's valid for me, others might experience it differently).

And then there was the final ingredient required for achieving blistering speed. I know this post shouldn't be about the process, but yet it's so crucial. A great process applied incorrectly steers you off the marble road, instead of keeping you on it !! I would group the chosen process, the technical abilities and skills of the team and the developer-client relationship into a big bag called the X-Factor. Why do i do that ? Well everything in this bag depends on everything else. You see, it all depends, and it's an art to establish which process would fit your circumstances and which not. Sure enough you could have on your team one or more star programmers, but there's not such caliber of highly skilled developers lurking everywhere and on every corner. Besides, what are the odds that your entire team consists of gurus and you've got this great big budget to support your adventures. Well if you work for Apple or Microsoft, maybe, but for the rest of us you'll need to improvise, adapt. And that's why i'm not going to go into detail with this last requirement ...

And those are the things we did as a team. It worked out very well in the end and the exercise was extremely productive. I'm not advocating that an iterative process and a pragmatic approach toward effective
development is the conclusive answer for shipping products faster, but i think that all these elements are essential in achieving that purpose. With a thorough understanding of the problem, by avoiding analysis paralysis, improving team communication and effectively modelling the business domain did speed up delivery manifold in our case.

Anyway, that's my post for July. Been a while but at least still alive ;)

Code Mess: Is research a culprit ?

2010-05-07T16:08:00.000-07:00

Sure enough, code affects the quality of other code.

"If he didn't care why should I ?"

But ... could current research be encouraging it ?

I attended the last day of ICSE Cape Town today, and was horrified to find new developments to assist in understanding poorly written code. A code summarizer could help us in navigating large code piles, but should it be used to understand poorly written code too ?

I believe we're suppose to learn from mistakes, and not neglect its consequences. Understanding the consequences of a poor choice, give us a reason for making a better decision next time. How could we ever fully comprehend the reason for doing things differently, if we ignore the repercussions ?

What did I do last time ? What is my next step again ? Ohh cum on ... what was I thinking ?
Questions like these arise either because:

You neglected to write your ideas down. Or...
You wrote such a complicated mesh of spaghetti code, you got lost in your own puddle of mud.

I conform to a different idea...
I believe code should be written so expressive that its intent is understood with ease.

Too many classes to navigate ?
How does the package structure look like ? Are the class names clear ? Have you used common patterns to express yourself ?

Maybe the application is becoming too large ?
You could decompose your app into smaller modules using OSGi, compile different apps and have them communice using web services, or consider using a service bus.

There's a reason for software nuasence. It's implying that we find a more elegant solution, a better implementation.
Simple manual tasks like appending different text files, or capturing data from documents into objects can be automated.
There's a reason many developers are called lazy, we don't want to continually repeat ourselves.
Many would use an automation tool when faced with the perils of repeating tasks.

The same applies to poor code. If a developer understands the pain, he should be able to understand the reason for cleaner code. He will start appreciating elegant solutions. Some might cultivate an affinity toward the art of expression.
Some learn, some don't, but most would learn that hacking away doesn't help in achieving the deadline.

Code summarizers are great tools, but will it cause us to be lazy for the WRONG reasons. Spending that extra few seconds finding an expressive name, used to pay off and be respected. Are we solving the pain and avoiding the cause ?

You used to find yourself refactoring an unmaintainable code base. Will a code summarizer allow us to comprehend garbage faster and give us a reason to lazily give garbage back ?
Maybe the answer is not the research, nor the technology its based on, not even the code itself.

Expression is an art, and the artist will continually review his creations until it achieves its cause.

Maintainable Code

2010-02-15T12:17:00.000-08:00

What is it ?
Writing something useful for your fellow programmers.
Code that is easily understood and is self-explanatory (the intent should be obvious).
A good approximation of where future enhancements will occur (you'll need a holistic view of the system for this one).
Design patterns used in the right places and at the right times.
Code that is efficient, ROBUST and elegant. Elegance improves and stimulates creativity.

The benefits.
It flattens the cost curve of your project. The projects' viability affects everyone.
Saves a lot of frustration and unproductive hours.
Eliminates ambiguous rules and the possibility of wrong interpretations. No "guessing" work.
Less time spend on poorly written constructs, more time spend on creative solutions.
Improves your reputation. The code you write is your legacy.
Saves a lot of wasted "development time". You've got a plan, and your code is evolving toward its intended design. Less time spend on rework and re-factoring.
Better adapts to changing client requirements.

How do I get there ?
Good place to start is the essence of your program, the code itself.
I am a firm believer of using meaningful variable names.
I try to write code like a poet would, we're writing a story after all.
Simple example:

if ((ivar == 3) && !(username == 'Tsepo') && !(username == 'Mandla')) {
// ....
}

What does that mean ?!? Why are we excluding 'Tsepo' and 'Mandla' ?
And what does 'ivar' represent, and when is the state 3 ?
Simply put, nobody knows what this construct is trying to accomplish.

Here is the same construct reworked:

if (isValidUser(username)) {
// ....
}

Now that's a lot clearer, and it makes sense.
That would be my first rule of writing sensible, maintainable code.
Group logic into their appropriate blocks or paragraphs.
The same rule applies to function arguments. More than 2 arguments makes
the function increasingly difficult to understand or comprehend.

If you end up having too many function arguments it either means:

You didn't apply object orientation correctly or thoroughly enough.
If you're not able to group argument state in an appropriate class, you might want to consider the Builder pattern.

The same goes for selector arguments. Like the one below to calculate the final result of a student:

public int calculateFinalResult(boolean fullTime) {
// ...
}

At the time there might only be two conditions for a student 'full time' and 'part time' fulfilling the boolean requirement. However, later we might want to add combined states like 'repeater part time', 'repeater full time' or even more elaborate states like 'part time repeater with disabilities'. All the different states implies different rules for computing a student's final result. A student with disabilities might be graded differently than others.

We could add more parameters to the function as necessary (repeater - first time) or pass an enum to clarify all possible disabilities. That's a bad idea. The more conditions and enumerations are passed as arguments, the larger, more complex and intricate the function becomes. It's better to keep functions focusing on a single task each (Single Responsibility Principle).

Surely the arguments exemplify dynamic behaviour, and from my previous post on design patterns
we would like to dis-entangle this "dynamic" logic from our code base.

The result; several smaller functions that are more flexible, easier to maintain and extend. The extracted functions might look something like this:

public Result calculateFinalResult(SubjectResults results) {
// ...
}

public SubjectResults buildSubjectResults() {
// ...
}

The second rule I would call aesthetic finishing.
Make it readable, understandable and beautiful.

That would include the following:

Writing sensible and useful comments.
That is, avoid tight coupling comments to your code base (refer to concepts, ideas and theorems instead of implementation details).
Deleting redundant code and comments the moment you find them.
Using clear and understandable names. The length of names are coupled to its scope, large functions will have longer names. Useful hint: whenever you have a conjunction in your name it probably gestures a violation of the SRP principle. E.g. A function with name calculateAndEmailFinalResult() is doing more than one task, in fact it calculates AND emails the result.

Finally, the last part:
Make it easily extend-able and reusable.

Identify points in the code base that are currently duplicated or bound to change frequently from changing requirements.

Changing requirements are either still immature or very visual to the client.
If requirements are still under an early stage of development and unclear, its bound to change sometime in the future.

The visual parts of the system can be made more maintainable by utilizing the MVP, MVC or similar "separation of logic" pattern [see ].

The unclear requirements can be catered for, by using a strong object-oriented approach and useful design patterns. Writing clean and understandable code also makes re-factoring easier.
It's very important to make ample use of tests in such a scenario. Since you'll be doing a lot of re-factoring you want functionality BEHAVIOUR to remain the same in unaffected parts of your system.

If requirements are changing so often, you can hardly keep up, it might be wise to re-examine the software process model you're using for the project. You're model would lie somewhere between the more Crafted (Agile methodologies) towards the more Controlled models (E.g. Waterfall process). Choosing the perfect model depends on the environment, size of the project and organisation, the level of skills available, deadlines, market conditions, internal politics, external forces like our current recession and many others ... But all that is due for a separate post on its own.

Further reading
Structure, aesthetics and flexibility. That sums up todays post.

For further information on:

Aesthetics: Clean Code, by Robert C. Martin; [ A real code-changing experience, highly recommend, also contains very useful smells & heuristics list in appendix. ]
Flexibility: Head First Design Patterns [ An easy read, a good introduction to the world of patterns. ]
Elements of Reusable Object-Oriented Software [An old time classic.]
Head First OOA&D [An easy intro to object orientation. ]

Test Driving Swing

2009-06-04T01:04:00.000-07:00

Recently I ended up test driving the front-end for my SCJD project. The easiest way to test drive a view technology, such as Swing, would be to move as much logic (business and view related) from your view as possible.

Why do I say that? The thinner and simpler a view is, the easier it is to test. The model-view-presenter architectural pattern by Martin Fowler does just that. I have to note that, the model-view-presenter now comes in two major forms "The passive view" and the "Supervising controller" patterns, with several other variations out there.

Anyway, I decided to use the "Supervising Controller" pattern with Abbot as my testing framework. The "passive view" seemed a bit "overkill", and I humbly acknowledge that it's still a pattern that I don't "get" at the moment ... haha.

The mvp works somewhat like this:

This leaves us with only two transitions to test, numbers (1) and (3). Transition (2) is not something we'll test. It's not contained in the view layer and would most probably be a call to some underlying service method. This service method would be tested separately. So we can create a mock object of the service method, assuming that it would perform the business logic correctly.

The two distinct tests we need to perform on the view are:

Test that the listener is working correctly (transition 1)

Test that the view's update method is working correctly (transition 2)

Sure, we could also test the layout, color, and font-size as well. But those things change all the time... Updating tests every time a cosmetic change is made, is just a royal waste of time. In my opinion, it's better to test the underlying "functionality" of your view. A back button that's not working is a horrible bug YOU DON'T WANT TO MAKE !!

To test the listener, I created a test-double. My view interface looks like this:


public interface ContractorSearchView {

 void registerSearchListener(ContractorSearchListener listener);

}

Remember, code to interfaces not implementations!! The listener interface looks like this:


public interface ContractorSearchListener {

 public void searchCriterionAdded(String criterion);
 
}

I started my test class by implementing the search listener, thus acting as a test double:


public class TestContractorSearchViewEventListener extends AbstractContratorTestFramework
  implements ContractorSearchListener {

The abstract test framework was something I wrote to ease the testing ...
It provides methods for creating mock data to simulate my tests with. However, in the end it's just an extension of the Abbot testing framework:


public abstract class AbstractContratorTestFramework extends AbstractSwingTestFramework

public abstract class AbstractSwingTestFramework extends ComponentTestFixture

As my test class was implementing the searchListener interface, I had to implement the following method:


 private String addedSearchCriterion;
 
 public void searchCriterionAdded(String criterion) {
  addedSearchCriterion = criterion;
 }

To set it all up, I had to create an implementation of the view interface, instantiate it, and then add my test class as the listener to it.


 @Override
 protected void setUp() throws Exception {
  super.setUp();
  addedSearchCriterion = null;
  ContractorSearchViewImplementation view = new ContractorSearchViewImplementation();
  view.registerSearchListener(this);
  showFrame(view);
 }

I then wrote my test case:


 public void testSearchEventGetsTriggered() throws Exception {
  // Given a search value is entered
  String criterion = "Search Me";
  typeIntoTextField("search_textfield", criterion);
  System.gc();
  
  // When the search button is clicked
  getTester().actionClick(namedComponent("search_button"));
  
  // Then expect the registered listener to receive the event
  assertEquals(criterion, addedSearchCriterion);
 }

The getTester() and typeIntoTextField(...) are helper methods I wrote that use the underlying Abbot framework. They're declared in the super class of my custom AbstractContratorTestFramework.


public abstract class AbstractSwingTestFramework extends ComponentTestFixture {

 private ComponentTester tester = new ComponentTester();
 
 protected ComponentTester getTester() {
  return tester;
 }

 protected void typeIntoTextField(String name, String value) throws Exception {
  tester.actionKeyString(namedComponent(name), value);
 }

 protected Component namedComponent(String name) throws Exception {
  return getFinder().find(new NameMatcher(name));
 } 
 
}

Of course the test didn't pass first time round, and I had to add some components in the view implementation...


public class ContractorSearchViewImplementation extends JPanel implements ContractorSearchView {

 private static final long serialVersionUID = 5752335740287943677L;
 private ContractorSearchListener searchListener;
 private JTextField searchField;
 private JButton searchButton;

 public ContractorSearchViewImplementation() {
  createWidgets();
  add(searchField);
  add(searchButton);
 }

 private JButton createWidgets() {
  searchField = createTextField("search_textfield");
  searchButton = new JButton();
  searchButton.setName("search_button");
  searchButton.addActionListener(new ActionListener() {
   public void actionPerformed(ActionEvent event) {
    String criterion = searchField.getText();
    searchListener.searchCriterionAdded(criterion);
   }   
  }
  );
  return searchButton;
 }

 private JTextField createTextField(String name) {
  JTextField field = new JTextField();
  field.setName(name);
  return field;
 }

 public void registerSearchListener(ContractorSearchListener listener) {
  this.searchListener = listener;
 }
}

Testing transition (2) or the view's update method, ended up being a little trickier.
The tricky part was that, I was using a table to display my search results. So I had to re-render / refresh my JTable every time the model was updated.
Thankfully Swing has a method that redraws the JTable if its data changed, the fireTableDataChanged() event...


 public void updateSearchResults(List searchResults) {
  ContractorTableModel tableModel = (ContractorTableModel) searchResultsTable.getModel();
  tableModel.setData(searchResults);
  tableModel.fireTableDataChanged();
 }

My complete test class for testing the view's update method looked like this:


public class TestContractorSearchViewModelUpdate extends AbstractContratorTestFramework {
 
 private ContractorSearchViewImplementation view;
 private JTable resultsTable;
 
 protected void setUp() throws Exception {
  super.setUp();
  resultsTable = null;
  view = new ContractorSearchViewImplementation();
  showFrame(view);
 }
 
 public void testSearchResultsUpdated() throws Exception {
  // Given a list of search results
  List searchResults = new ArrayList();
  searchResults.add(returnMockContractor_IT());
  searchResults.add(returnMockContractor_PLUMBING());
  
  // When the update method on view is called
  view.updateSearchResults(searchResults);
  System.gc();
  
  // Then the expected results should be displayed
  resultsTable = (JTable) namedComponent("results_table"); 
  assertITContractor();
  assertPlumbingContractor();
 }
 
 private void assertITContractor() {
  int rowIndexForITcontractor = 0;
  Contractor ITContractor = returnMockContractor_IT();
  assertEquals(ITContractor.getName(), returnDisplayedContractorNameAtRow(rowIndexForITcontractor));
  assertEquals(ITContractor.getLocation(), returnDisplayedContractorLocationAtRow(rowIndexForITcontractor));
  assertEquals(ITContractor.getHourlyCharge(), returnDisplayedContractorHourlyRateAtRow(rowIndexForITcontractor));
 }

 private void assertPlumbingContractor() {
  int rowIndexForPlumbingContractor = 1;
  Contractor PlumbingContractor = returnMockContractor_PLUMBING();
  assertEquals(PlumbingContractor.getName(), returnDisplayedContractorNameAtRow(rowIndexForPlumbingContractor));
  assertEquals(PlumbingContractor.getLocation(), returnDisplayedContractorLocationAtRow(rowIndexForPlumbingContractor));
  assertEquals(PlumbingContractor.getHourlyCharge(), returnDisplayedContractorHourlyRateAtRow(rowIndexForPlumbingContractor));
 } 
 
 private String returnDisplayedContractorNameAtRow(int rowIndex) {
  return (String) resultsTable.getModel().getValueAt(rowIndex, ContractorTableColumn.NAME_COLUMN.getCode());
 }

 private String returnDisplayedContractorLocationAtRow(int rowIndex) {
  return (String) resultsTable.getModel().getValueAt(rowIndex, ContractorTableColumn.LOCATION_COLUMN.getCode());
 } 
 
 private Double returnDisplayedContractorHourlyRateAtRow(int rowIndex) {
  return (Double) resultsTable.getModel().getValueAt(rowIndex, ContractorTableColumn.HOURLY_CHARGE_COLUMN.getCode());
 } 
 
}

With my view's implementation like so...


public class ContractorSearchViewImplementation extends JPanel implements ContractorSearchView {

 private static final long serialVersionUID = 5752335740287943677L;
 private ContractorSearchListener additionListener;
 private JTextField searchField;
 private JButton searchButton;
 private JTable searchResultsTable;
 
 public ContractorSearchViewImplementation() {
  createWidgets();
  add(searchField);
  add(searchButton);
  add(searchResultsTable);
 }

 private JButton createWidgets() {
  searchField = createTextField("search_textfield");
  searchResultsTable = createJTable("results_table");
  searchButton = new JButton();
  searchButton.setName("search_button");
  searchButton.addActionListener(new ActionListener() {
   public void actionPerformed(ActionEvent event) {
    String criterion = searchField.getText();
    additionListener.searchCriterionAdded(criterion);
   }   
  }
  );
  return searchButton;
 }
 
 private JTable createJTable(String name) {
  JTable table = new JTable(createTableModel());
  table.setName(name);
  return table;
 }

 private JTextField createTextField(String name) {
  JTextField field = new JTextField();
  field.setName(name);
  return field;
 }
 
 private TableModel createTableModel() {
  ContractorTableModel tableModel = new ContractorTableModel();
  return tableModel;
 }
 
 public void registerSearchListener(ContractorSearchListener listener) {
  this.additionListener = listener;
 }

 public void updateSearchResults(List searchResults) {
  ContractorTableModel tableModel = (ContractorTableModel) searchResultsTable.getModel();
  tableModel.setData(searchResults);
  tableModel.fireTableDataChanged();
 }
 
}

It's important to remember that we only tested the two transitions that effect the view, namely transition (1) and transition (3). The next step would be to test the presenter and then the service method used to retrieve/update the results.

But how does the presenter fit into the entire picture? Well as its constructor the presenter would take two arguments. One would be the view you're updating, the other would be the model object received from the view (if no data capturing took place, then the model would be the same from the last call to the view's update method).

The presenter then adds the listener to the view object. Important... there is no concrete implementation for the listener, it's created inside the presenter as an anonymous inner class.

Then whenever an event occurs, the presenter invokes the service method, and then makes a call to the view's update method, to update itself with the latest data.
To end off, here's an example of how it's done. In this scenario I had no data to update from my view, I merely needed to display search results given the passed criteria...


public class ContractorSearchPresenter {

 private ContractorService contractorService;
 private ContractorSearchView contractorSearchView;
 private List searchResults;
 
 public ContractorSearchPresenter(ContractorSearchView givenContractorSearchView) {
  this.contractorSearchView = givenContractorSearchView;
  contractorSearchView.registerSearchListener(new ContractorSearchListener() {

   public void searchCriterionAdded(String criterion) {
    searchResults = contractorService.searchByName(criterion);
    updateView();
   }
   
  });
  updateView();
 }
 
 private void updateView() {
  contractorSearchView.updateSearchResults(searchResults);
 }
 
 public void setService(ContractorService givenContractorService) {
  this.contractorService = givenContractorService;
 }
 
}

So that's how to test drive your Swing application front-end :)

JUnit for Jasper Reports

2009-04-16T08:13:00.000-07:00

Finally ... today I had a chance, between hectic schedules, to write our first JUnit for Jasper reports. GOOGLE wasn't friendly this time, so had a clean canvas to work from :)

The repeating hurdle I faced was that I'm required to design and develop a report well before any of the database structures or data is captured within the system. It's like trying to extract a report on something that doesn't exist yet ... how funny ...

To make matters worse, the database table structure is like a spiders web. Finally, although unfortunate, I had a chance to work in Brian's Big Balls of Mud http://www.laputan.org/mud/ scenario. Pre-populating database tables with "dummy" data is close to impossible in my case. Our report query's end up having a norm of 14 inner joins ... not a pretty sight at all.

The TDD approaches the problem from a different perspective. My idea was to pass a collection of expected results to the report, and then assert the output. I like to think of it as a black box ... by sending some input, and knowing the expected output values, you should be able to assert that the black box is functioning correctly ...

From the diagram, X would be the input values, Y the results that I expect to receive, and T(x) the report that I'm testing.

I started off by first creating a new report. The report contains a single text field that get's populated by a data-source. The other text boxes all contain static text and won't change given different input values. The report is shown below:

In Jasper there is two different types of input, one would be report parameters (mostly used to filter query results of a report), the second, field values (values retrieved from the database, using the report query).

I started off by creating a java.util.Map containing field values. This would be analogous to the data retrieved from a SQL query run by the report.

private static Map data;
private static List<Map<String, Object>> dataCollection = new ArrayList<Map<String,Object>>();

{
data = new HashMap<String, Object>();

// Add expected field data
data.put("POST_ADDR", "THE ADDRESS");

// Add the Hash-map data to a collection
dataCollection.add(data);
}

The Map of field values are added to a collection, which in turn is used to populate a Jasper data-source.

    // Setup the data-source with expected data values
dataSource = new JRMapCollectionDataSource(dataCollection);

I created a parameter as well ...

// Construct required parameters for the report
parameterNameToValue = new Hashtable();
parameterNameToValue.put("PRINT_IT", new Long(1L));

I then added the "mock" data-source and parameter to Jasper's fill manager ...

// Given the setup data-source and parameter mappings
// When the report is run
String jasperReport = "C:\\DEV_WORKSPACE\\TextExporter\\src\\templates\\classic.jasper";
JasperPrint print = JasperFillManager.fillReport(jasperReport, parameterNameToValue, dataSource);

I then ran the test ...

The awesome part to specifying the reports' data-source inside the unit test, was that it temporarily ignores any data-source specified in the report itself. To illustrate this I first ran the report inside iReport http://www.jaspersoft.com/JasperSoft_iReport.html,

The text field accurately displayed the contents inside the database, namely PO BOX 515.
I then ran the same report inside the unit test, using the "mock" data-source ... the result was

which corresponds to the field value I specified in the unit-test.

Even though its good to visually inspect your report, we're writing a unit test, and would like to assert that these values are correct inside the unit test. I accomplished just that, by inspecting the JasperPrint objects' page and element values. Since we only have one page, I only needed to retrieve elements on the first page.


List pages = print.getPages();
JRPrintPage pageToTest = pages.get(0);
List pageElements = pageToTest.getElements();

Every Jasper element has a key value. The text field I was testing against had the key name 'textField-1'. I iterated inside a loop until I found the element


for (Iterator iterator = pageElements.iterator(); iterator.hasNext();)   JRPrintElement element = (JRPrintElement) iterator.next();
 if(element.getKey().equals("textField-1")) {

and then asserted the expected value is displayed


textField = (JRTemplatePrintText) element;
Assert.assertEquals("THE ADDRESS", textField.getText());

I ran the test case again and it passed !!

The power from asserting display values inside a unit-test is when we want to test against some decision logic inside the report. I added a print condition on the text field. I did this using the parameter specified in the unit-test.


parameterNameToValue = new Hashtable();
parameterNameToValue.put("PRINT_IT", new Long(1L));

Inside iReport we would need to specify the parameter as well. This was done like so:

The print condition was added to the text field like so:

Since the PRINT_IT was given a value of 1 in the unit-test, the test passed again.

Changing the parameter value to 0 instead, caused it to fail as expected.

My sample prototype was working and it was time to expand on my morning endeavors. So during the afternoon, I re-factored the code. I created a base test class from which all future unit-tests can be based on:


import net.sf.jasperreports.engine.JRPrintPage;
import net.sf.jasperreports.engine.JasperFillManager;
import net.sf.jasperreports.engine.JasperPrint;
import net.sf.jasperreports.engine.data.JRMapCollectionDataSource;
import net.sf.jasperreports.engine.fill.JRTemplatePrintText;

import org.junit.Assert;


public class JasperPrintTest extends TestCase {

 private Map<String, Object> data;
 private List<Map<String, Object>> dataCollection;

 private JRDataSource dataSource; 
 private Map<String, Object> parameterNameToValue;
 private String jasperReport;
 private Exporter exporter;
 private JasperPrint print;

 public void setUp() throws Exception {

  // Add the hash-map of Field values to the collection
  dataCollection = new ArrayList<Map<String,Object>>();
  dataCollection.add(data);

  // Setup the data-source with expected data values
  dataSource = new JRMapCollectionDataSource(dataCollection);
 }

 /**
  * 
  * @param expectedResults Map of key-value pairs
  * @throws Exception
  */
 @SuppressWarnings("unchecked")
 public void testPrint(Map<String, Object> expectedResults) throws Exception {

  // Given the setup data-source and parameter mappings

  // When the report is run  
  print = JasperFillManager.fillReport(jasperReport, parameterNameToValue, dataSource);

  // Then assert that the result has the expected value
  List<JRPrintPage> pages = print.getPages();
  for (Iterator iterator = pages.iterator(); iterator.hasNext();) {
   JRPrintPage pageToTest = (JRPrintPage) iterator.next();
   List<JRPrintElement> pageElements = pageToTest.getElements();

   JRTemplatePrintText textField = null;
   for (Iterator element_iterator = pageElements.iterator(); element_iterator.hasNext();) {
    JRPrintElement element = (JRPrintElement) element_iterator.next();
    if(expectedResults.keySet().contains(element.getKey())) {
     textField = (JRTemplatePrintText) element;
     Assert.assertEquals(expectedResults.get(element.getKey()), textField.getText());
     break;
    }
   }
  }  
 }

 public void exportResults(int height, int width, String fileName) throws JRException {
  exporter.export(print, height, width, fileName);  
 }

 public void setData(Map<String, Object> data) {
  this.data = data;
 }

 public void setParameterNameToValue(Map<String, Object> parameterNameToValue) {
  this.parameterNameToValue = parameterNameToValue;
 }

 public void setJasperReport(String jasperReport) {
  this.jasperReport = jasperReport;
 }

 public void setExporter(Exporter exporter) {
  this.exporter = exporter;
 }

 public Map<String, Object> getData() {
  return data;
 }

}

The idea is to pass the expected results (or output) to this underlying class from your unit test. I successfully wrote a test case (using this custom base class) for the most recent report I had to design. Below is the entire test case, testing several scenarios in each test method.


import java.util.HashMap;
import java.util.Hashtable;
import java.util.Map;

import org.junit.Before;
import org.junit.Test;


public class SORSupplementaryPrintTest extends JasperPrintTest {

 Map<String, Object> fieldData;

 @Before
 public void setUp() throws Exception {
  fieldData = new HashMap<String, Object>();
  fieldData.put("EXAM_CENTRE", "centre");
  fieldData.put("CIRCUIT", "circuit");
  fieldData.put("REGION", "region");
  fieldData.put("EXAM_PERIOD_DESC", "                    ");
  fieldData.put("EXAM_CENTRE_POST_ADR", "                    ");
  fieldData.put("EXAM_CENTRE_POST_CODE", "                    ");
  fieldData.put("PROVINCE", "                    ");
  fieldData.put("PROV_CODE", "                    ");
  fieldData.put("SOR_NUMBER", new java.math.BigDecimal(0));
  fieldData.put("EXAMINATION_NUMBER", new java.math.BigDecimal(0));
  fieldData.put("ID_NUMBER", "88778");
  fieldData.put("PASSPORT_NUMBER", "002900");
  fieldData.put("IMMIGRANT", new java.math.BigDecimal(0));
  fieldData.put("DATE_OF_BIRTH", new oracle.sql.TIMESTAMP());
  fieldData.put("CANDIDATE", "candidate");
  fieldData.put("CANDIDATE_SURNAME", "surname");
  fieldData.put("POSTAL_ADDRESS", "postal address");
  fieldData.put("POSTAL_CODE", "postal code");
  fieldData.put("SUBJECT_CODE", "subject code");
  fieldData.put("ALPHA_CODE", "alpha code");
  fieldData.put("SUBJECT_NUMERIC_CODE", new java.math.BigDecimal(0));
  fieldData.put("SUBJECT_DESC", "subject description");
  fieldData.put("SUBJECT_TABLE_LID", new java.math.BigDecimal(1));
  fieldData.put("ENROLLMENT_ID", new java.math.BigDecimal(1));
  fieldData.put("WORDS_PER_MINUTE", new java.math.BigDecimal(0));
  fieldData.put("DEC_PERC" , new java.math.BigDecimal(0));
  fieldData.put("MARKSHEET_STATUS_ID" , new java.math.BigDecimal(0));
  fieldData.put("ACTIVE_IRREGS" , new java.math.BigDecimal(0));
  fieldData.put("GUILTY_IRREGS" , new java.math.BigDecimal(0));
  fieldData.put("SUPL_PERC" , new java.math.BigDecimal(0));
  fieldData.put("RESULT_ID" , new java.math.BigDecimal(0));
  fieldData.put("CERTIFICATE_LANGUAGE_ID" , new java.math.BigDecimal(0));
  fieldData.put("PAPER_LANGUAGE_ID" , new java.math.BigDecimal(0));
  fieldData.put("PROMOTION_TYPE_ID" , new java.math.BigDecimal(0));
  fieldData.put("ENROL_WITH_SPECIAL_CONDITIONS" , new java.math.BigDecimal(0));
  fieldData.put("QUALIFIES_FOR_SUPLEMENTARY" , new java.math.BigDecimal(0));
  fieldData.put("REGION_CODE", "                           ");
  fieldData.put("CIRCUIT_CODE", "                           ");
  fieldData.put("CEN_ID" , new java.math.BigDecimal(0));
  fieldData.put("EXAM_CENTRE_CODE", "                           ");
  fieldData.put("IS_MAIN_REG" , new java.math.BigDecimal(0));
  fieldData.put("MAIN_RESULT_ID" , new java.math.BigDecimal(0));
  fieldData.put("SUPL_RESULT_ID" , new java.math.BigDecimal(0));
  fieldData.put("SUBJECT_PERC_ROUNDED" , new java.math.BigDecimal(0));
  fieldData.put("EXAM_YEAR", new java.math.BigDecimal(2009));
  super.setData(fieldData);
  
  Map<String, Object> parameterNameToValue = new Hashtable<String, Object>();
  parameterNameToValue.put("LOCATION_ID", new Long(1L));
  parameterNameToValue.put("EXAM_PERIOD_ID", new Long(1L));
  super.setParameterNameToValue(parameterNameToValue);
  
  super.setJasperReport("C:\\DEV_WORKSPACE\\MARCH_BRANCH\\src\\server\\prod\\com\\magnafs\\iecs\\reports\\StatementOfResults\\SupplementaryStatementOfResultsPerLocText.jasper");
  super.setExporter(new TextExporter());
 }

 @Test
 public void testShouldPrintMarchDateAchievedForSupplementaryRegistration() throws Exception {
  
  // Given an improved promotion status
  // Given it is a supplementary registration
  super.getData().put("RESULT_ID", new java.math.BigDecimal(100084)); 
  super.getData().put("SUPL_RESULT_ID", new java.math.BigDecimal(100086));
  super.getData().put("IS_MAIN_REG", new java.math.BigDecimal(0));
  super.setUp();  

  // Expect these results 
  Map<String, Object> expectedResults = new HashMap<String, Object>();
  expectedResults.put("textField-33", "MAR 2009");
  
  // When the report is generated
  super.testPrint(expectedResults);
  
 }
 
 @Test
 public void testShouldPrintMarchDateAchievedForGreaterSupplementaryResult() throws Exception {
  
  // Given an improved promotion status
  // Given it is a main registration
  // Given the supplementary result is greater than the December result 
  super.getData().put("RESULT_ID", new java.math.BigDecimal(100084)); 
  super.getData().put("SUPL_RESULT_ID", new java.math.BigDecimal(100086));
  super.getData().put("IS_MAIN_REG", new java.math.BigDecimal(1));
  super.getData().put("DEC_PERC", new java.math.BigDecimal(27));
  super.getData().put("SUPL_PERC", new java.math.BigDecimal(96));
  super.setUp();  

  // Expect these results 
  Map<String, Object> expectedResults = new HashMap<String, Object>();
  expectedResults.put("textField-33", "MAR 2009");
  
  // When the report is generated
  super.testPrint(expectedResults);
  
 }  
 
 @Test
 public void testShouldPrintNovemberDateAchievedForGreaterDecemberResult() throws Exception {
  
  // Given an improved promotion status
  // Given it is a main registration
  // Given the December result is greater than the supplementary result 
  super.getData().put("RESULT_ID", new java.math.BigDecimal(100084)); 
  super.getData().put("SUPL_RESULT_ID", new java.math.BigDecimal(100086));
  super.getData().put("IS_MAIN_REG", new java.math.BigDecimal(1));
  super.getData().put("DEC_PERC", new java.math.BigDecimal(56));
  super.getData().put("SUPL_PERC", new java.math.BigDecimal(48));
  super.setUp();  

  // Expect these results 
  Map<String, Object> expectedResults = new HashMap<String, Object>();
  expectedResults.put("textField-33", "NOV 2008");
  
  // When the report is generated
  super.testPrint(expectedResults);
  
  // Test view the report results
  super.exportResults(64, 100, "C:\\DEV_WORKSPACE\\TextExporter\\src\\results\\exportResults.txt");
 } 
}

Where to log exceptions ? How to handle them ?

2009-04-08T04:38:00.000-07:00

While working on my SCJD project, I encountered a hurdle in the road. SUN explicitly gives us an interface which we must implement for database operations. We're not allowed to change it or deviate from this interface.

The interface methods declare exceptions for a record not found. However, some third party classes like the RandomAcessFile class, throw additional exceptions like FileNotFoundException, IOException and EOFException. Throwing a IOException doesn't necessarily mean that the record couldn't be found ...

Basically, there are three tiers (or levels) to log your exceptions in:

Bottom level tier: Logging the exception where it first occurred (somewhere at the Data Access layer ... or even lower maybe ?).

Middle level tier: Logging higher up the call stack, where more information is available (probably at the services or business layer).

Top level tier: Propagating your exception all the way to the GUI (all the display details in the MVC architecture).

Logging at the bottom level may cause problems. For example, if SUN's RandomAcessFile were to handle the FileNotFoundException internally, there would be no way for me to know what caused the problem in the first place. If an exception was thrown in the data access layer, and it get's swallowed up, what do I tell the user ? Even worse ... what if ... while performing a write or update on the database, a database exception is thrown? Surely, a roll back needs to happen? Do I retry the database operation, or do I propagate it higher up the call stack?

Logging higher up will allow you to wrap the exceptions and add additional information as it's propagated up the call stack. It might help putting exceptions into perspective. This component called this one, which called component X that threw the exception.

In my opinion, propagating exceptions all the way to the top level of the stack, should only happen if you need to display a relevant message to the user. Handling exceptions at the top level, is a means of dealing exceptions centrally at one place. However, so would using AOP as well

In my case, for the project, adding AOP is overkill to implement from scratch (We're not allowed to use anything besides the standard Java API). I don't think that having a fixed interface is that uncommon. Working on a project, with a fixed interface to another system is a reasonable and realistic scenario that may occur.

From the SCJD Exam with J2SE 5 Platform I have 5 choices.

Swallow the exception: The exception is caught but not not dealt with (Neither logged or propagated).

Just log the exception

Wrap the exception within an allowed exception

Wrap the exception within a RuntimeException

Wrap the exception within a subclass of RuntimeException

So ... it boils down to ... ignoring the exception, logging it or just propagating it higher up the call stack. Ignoring the exception would be a NO outright. Choosing to either log or propagate the exception would probably come down to this:

Will the user want to know what occurred?

Will the user be able to correct or rectify the situation?

Is enough information available to log the exception in its context?

There might be more factors to consider than the three I mentioned, but it gives you a reasonable idea on what to do.

To come back to my scenario, with the FileNotFoundException, I've decided to propagate all the way. Not having a database anymore (a file based system in this case) is a major problem ! At least if the user get's the exception, the DBA might have a look at it... :)

SCJD - Update

2009-04-04T13:25:00.001-07:00

Finally !! ... I'm working on my SCJD project again. I recommend reading

SCJD by Andrew Monkhouse and Terry Camerlengo

before you begin. It gives a good idea on what to expect.

I've decided to follow the TDD (Test Driven Development) approach. It's preferred to write your first test case in the GUI layer. The GUI is high-level, abstract and it's the first thing the client will notice. Beginning at the graphics level sets client expectations, and allows for feature requests early-on during development.

My first few minutes have been rewarding, helping me identify scenarios I'd probably never have thought of otherwise. I started writing a test method for one of the API methods specified by SUN (just to test the waters ... so to speak).

The test case is used to test the reading of a record from the DB. I needed to create an implementation class for the API method. I wanted to use a design pattern right away ... but then realized again ... never use a design pattern if there's no need for it yet !

First I wrote my story:


// As a CSR
// I want to retrieve an existing DB record
// So that I can view the record data
public class ReadRecordTest {

Then I wrote the test:


 @Test
 public void testReadExistingRecord() throws Exception {
  
  // Given a database file
  File databaseFile = new File("test/suncertify/db/db-2x2.db");
  
  // When I call the DB read method
  DBAccess dbAccess = new DBAccessImplementation(databaseFile);
  String[] record = dbAccess.readRecord(1L);
  
  // Then a complete DB record should be returned
  Assert.assertNotNull(record);
 }

First try and it failed. I had a look at my implementation class, and realized it wasn't doing anything ...


 @Override
 public String[] readRecord(long recNo) throws RecordNotFoundException {
               return null;
 }

I made it pass by returning some fixed value instead, like so:


 @Override
 public String[] readRecord(long recNo) throws RecordNotFoundException {
  String[] record = {"t", "g"}; 
  return record;
 }

Yes ... it's obvious that I'm "making" the test pass. That, however, is the mindset of TDD. Write a story and then test until you make it pass.

The next step, was the inverse of the first.


 @Test(expected=RecordNotFoundException.class)
 public void testReadNonExistingRecord() throws RecordNotFoundException {
  
  // Given a database file
  File databaseFile = new File("test/suncertify/db/db-2x2.db");
  
  // When I call the DB read method, for a non-existing record
  DBAccess dbAccess = new DBAccessImplementation(databaseFile);
  String[] record = dbAccess.readRecord(1L);
  
  // Then I expect an exception to be thrown
 }

As expected, this test failed. I had to go back to the implementation and actually retrieve data for the tests to work. This was just a basic example of TDD. It helps you identify those code bugs that pass 90% of the time, but fail the rest.

How to discover a new Design Pattern ?

2009-02-01T02:21:00.001-08:00

Design Patterns are found after hard work and experience. Every situation is different, and good judgment is needed to know when to use one.

Thankfully many patterns have been cataloged already. But what if you can't find a pattern for your problem ? The answer would be to discover a new one.

Patterns aren't fixed in stone. You may combine them, alter them, and adapt them for your unique situation. Whether your new pattern utilizes existing ones doesn't matter, the underlying principles for finding the pattern still remains the same.

I've made a list of principles for discovering a new design pattern below:

Encapsulate what varies

Favour composition over inheritance

Program to interfaces, not implementations

Encapsulate what varies

The idea is to capture code that changes often and make it a reusable component. First you'll need to determine what is changing all the time, and then later make logical groupings of the code that changes.

Favour composition over inheritance

Beware of making everything an "IS-A" relationship. Sometimes a "HAS-A" relationship would be more beneficial. In fact it's better to favour "HAS-A" associations over "IS-A" associations whenever possible. Why do I say that ? Well ... "HAS-A" associations are related to encapsulations; you're capturing a sample of code and injecting it into another class as a property. If we were to make the property field an interface instead, we would be able to interchangeably inject several different implementations. This is an ideal property for creating reusable components. You might be thinking I'm refering to the strategy pattern in particular, however the underlying principle applies to all other patterns: "We want to make a seperate reusable component, which implies a seperate class with its own interface".

Program to interfaces, not implementations

Whenever a composition is created, it makes logical sense to extract an interface (good object-oriented programming). Thus the opposite is also true; program to an interface and you'll end up with several small reusable components (in theory of course ;)

Reflection: When to use it ... when NOT.

2009-01-04T10:37:00.000-08:00

Code transparency, it's something we should ALL strive towards. Code transparency means you compartmentalize your code into separate regions of concern. The benefits ... change one part of the system and limit the damage done to the other parts. The lightweight (Model View Controller) pattern became famous for that very reason. However, the MVC is not the only way to make your code transparent.

The Spring framework (along with the MVC pattern) gave us a no-intrusion framework that uses XML configuration files to pilot the system where you want it to go. It also makes use of reflection and dependency injection, in order to generalize and compartmentalize the framework code of the underlying system (so you don't need to embed horrible framework code even if only annotated ... EJB's blargghhh).

The benefits of transparent code are endless, and reflection is a way and a means to achieve that goal. Using reflection we can build generalized services that will eliminate most of that terrible copy - paste habits.

Start by asking yourself: is this a general need in the system, or, a specific one ? If you're unsure then your best bet is NOT to use reflection. Delaying your decision for using reflection could save you in the long run, especially after problem patterns and user requirements change.

However, if you need to access an object's features in a general way, reflection becomes very useful. One such a scenario would be an XML emitter (like Castor). Maybe you're implementing a new Web Service technology from scratch and want to send over object state parsed to XML. To custom write XML for every object type (class) would be a very long, tedious and error prone approach. A much simpler solution would be to inspect a parsed in object, and build up your XML structure dynamically using the reflection API.

Another scenario where you could make use of reflection is with persistence (Hibernate is an excellent example). By inspecting the return types, and field associations it's possible to build up the corresponding SQL statements dynamically. The point is that whenever you perform some general action on objects (whether only inspecting it, or even modifying it) , reflection becomes handy. Yes ... there is still a performance penalty, but not so much as it use to. SUN MICROSYSTEMS have done an excellent job in improving reflection performance over the years (in particular, Java 6). These days, the benefits of reflection far outway the performance penalties when used appropriately.

To get you started, below is a short intro to the reflection API.

The reflection API allows you to inspect the definitions (including the names and modifiers) of:

Classes
Methods [java.lang.reflect.Method] , and
Fields [java.lang.reflect.Field]

Start by importing the reflection API into your project: import java.lang.reflect.*;

Accessing the class

Two ways to inspect a particular class, either use:

Class c = Class.forName("className")

or,

Class c = obj.getClass();

where Object obj = new className(); and c is of type className.

Accessing the method

You only need to have the class type (as determined above) in order to find all the methods of that class. Calling getMethods() on the class type will return an array with ALL the supported methods of that class (including the ones inherited from its super class). The getDeclaredMethods() method returns an array of only the methods DECLARED in that specific class. The returned value is an array of java.lang.reflection.Method types.

It's also possible to determine the parameter types of a method by calling getParameterTypes() on the java.lang.reflection.Method type you found above.

Example below:


public static void printMethods(Object obj) throws Exception {

    Class cls = obj.getClass();
    Method[] methods = cls.getDeclaredMethods();
    for (int methodIndex = 0; methodIndex < methods.length; methodIndex ++) { 
        Method inspectedMethod = methods[methodIndex ]; 
        Log.info("The method name is: "+inspectedMethod.getName());
       
        Class[] parameterTypes = method.getParameterTypes();
        for (parameterIndex = 0; parameterIndex < parameterTypes.length; parameterIndex++) {
            StringBuilder sb = new StringBuilder()
                .append(" Parameter ") .append(parameterIndex)
                .append(" is of type: ")
                .append(parameterTypes[parameterIndex].toString());
            log.info(sb.toString()); 
        }
    }
}

Accessing the field

Retrieve all the fields of a certain class by calling getDeclaredFields() on that method.
This will return an array of java.lang.reflect.Field types. It's possible to go even one step further and determine the modifiers (static, volatile etc) of that field by calling getModifiers() on it.

To determine the field type call getType() on that field. To get it's value is a two step process.
First set its accessibility value so it can be accessed by the java.lang.reflect package even if it's a private field. This can be done so:


   Field inspectedField = fields[i];
   inspectedField.setAccessible(true);

Then to retrieve the field value do this:


   Object value = field.get(objInstance);

, where objInstance is the object whose field value you'd like to know.

Pressure

2008-12-24T12:57:00.000-08:00

12 hours. That is what I have to design, develop and test a report. Not an ordinary report, but that one that could drastically change the course of our nation. Approximately 600 000 people are waiting for me to roll this out to live deployment (printing tomorrow night nationwide). The quality and correctness of this report, will in effect change the course and lives of 600 000 people. It WILL change the political landscape of an entire country. Can we move the deadline ... impossible ... there's no other way. It's then or never.

Will it be a success, I don't know. Two things I'm sure of, one whatever the outcome, I tried my best. The other, well I can't let you know, it might just reach AM, PM, CNN, BCC and probably every major news station in the world. [That's not going to help at all ... not my career, nor anyone else with me].

There is a problem though, the technology to use is not working. We can't change that now (it's too late ... LOL). Only one way out, try to find another way of doing it, another way of solving a problem that can't be solved [but what can't be solved ?!?]. Working in IT, working under pressure like that, it's not always that healthy. But darn, you can't say that you're not having any fun.

Debugging your GWT in Eclipse

2008-10-31T00:33:00.000-07:00

Using your IDE's debugging ability just adds another tool to your set when writing software, and could become very handy at times.

This example is based upon the Red Hat Developer Studio, which is basically some additional plugins to your normal Eclipse environment.

The first step to setting up your debug ability is to create a new debugging scenario. Select the "Debug as ... " drop down and select "Open Debug Dialog". The screen displayed should look like the one below.

At the project input, click the "Browse ..." button and select your project.

[Still in progress - will complete this post a bit later]

How to audit your code ?

2008-10-30T10:51:00.000-07:00

Today I thought about this again. We're currently using DB triggers to log our audit data. We're going to rework the project, so yes, adding the audit structures is still on the TODO list. But anyway ... why not do it in the DB ? Well ... simply maintenance.

Using AOP proves to be way better. Cutting across your entire application, and using Java's reflection API, you could write a nice Audit Interceptor to log all your activity.

Storing your audit data in the DB is just going to increase your application's transaction overhead and degrade response time. Why everybody seems to be storing their log data in the DB, I don't really have a clue. Maybe it's all about reliability and securing your data ? Don't want to lose that very important audit file on your file system ... But, what happened to just assigning user privileges to your log files, or even making backups if you're really that paranoid ? Using that LogFactory proves to be useful for auditing after all.

Anyhow, for those that don't know much about AOP ... yet ... here's a primer:

I think of AOP as some kind of interceptor, a listener of sorts. Imagine a long line connecting two points in space. Information is travelling along this line, but you'd like to know more about the information. So you put some sort of listening device (called an advice in AOP terminology) at the line. Inside this advice your allowed to modify the content of the information, process it, or even use it to perform some other decision logic or tasks. The place where you connect your advice to the communication link is called your join point. Now imagine multiple data links, which ones you connect to with your advice is called your point cut.

The great thing about AOP is that it's able to encapsulate the scattered code of your application. Whenever you've got some common functionality scattered across your entire application, consider using AOP or a Filter. A filter will be more useful for the communication link to the outside world of your application, while AOP would be more useful for the communication link inside it.

JEE Pattern: The Intercepting Filter [part 1]

2008-09-19T14:15:00.000-07:00

Logging, security, compression, network analysis, and even HTML decoration all make use of the request-response packets going from and to your application. When writing some component (maybe even with the intention of being reusable) to perform the task(s) at hand, you would probably end up with some "if-then-else" decision logic. This would control the packet stream's flow of execution. However, you'll probably end up with duplicate code in multiple (if not all) conditional branches of your control unit; all performing the same task. Furthermore, hard coding the flow of control will probably result in an application specific solution.

The dynamic behaviour in this context would be the individual/unique operations performed by each process unit for logging, security etc. The static behaviour in this context would be the packet stream itself. To write a reusable component we would need to capture the dynamic content and encapsulate it. Rather than having a component with decision logic to address every conceivable configuration or setup, we could instead use several smaller components that are declared declaratively. These components would then be declared in a configuration file, each one contributing to the application's specific need.

The small individual components would add small features such as logging or security to the system, thus encapsulating the dynamic behaviour. For reusability, it is important to decouple these components from any application specific code. The best place to put these components would either be before or after the packet stream enters the application. This leads to the definition of the terms pre-processing and post-processing of an incoming HTTP request. The individual, reusable components are called filters.

The Servlet Specification, version 2.3, includes a standard mechanism for building filter chains and unobtrusively adding or removing filters from those chains. To build up this chain of filters, some sort of filter-to-filter communication would be needed. How would a filter know which filter to send to next ? The solution is to use a filter manager. The filter manager will read an application's filter configuration file and use it to manage the filtering process. Each filter would then need to adhere to some common filter interface so that the manager would know how to invoke each one. This is called the Standard Filter Strategy and is only one of many strategy's for applying the Intercepting Filter pattern.

The code below gives you an idea of how a filter looks like. The doFilter method will cause the next filter in the filter chain to be executed. A request would enter the first filter in the filter chain and move through consecutive filters until it enters the application itself. Upon return, the response would move through the same filters, but this time in the opposite order.

/**
* This code is from an example within "core J2EE PATTERNS, Best Practices and Design
* Strategies".
**/
public class BaseEncodingFilter implements javax.servlet.Filter {
private javax.servlet.FilterConfig filterConfig;

public void doFilter(javax.servlet.ServletRequest servletRequest,
javax.servlet.ServletResponse servletResponse,
javax.servlet.FilterChain filterChain)
throws java.io.IOException, javax.servlet.ServletException {
filterChain.doFilter(servletRequest, servletResponse);
}

protected javax.servlet.FilterConfig getFilterConfig() {
return filterConfig;
}

public void destroy() { }

public void init(javax.servlet.FilterConfig filterConfig)
throws javax.servlet.ServletException
this.filterConfig = filterConfig;
}
}

In the subsequent parts, I will elaborate more on other Intercepting Filter strategies
and the filter process overall to eventually write a complete Filter component.

Entity Manager: Persistence in EJB3

2008-09-16T11:01:00.001-07:00

The entity persistence manager for EJB is a common interface to your ORM of choice (allowing you to choose between Hibernate, Ibatis and others). When confronted with a situation where the EJB QL is not specific enough for your needs consider using a native query.

The EJB framework allows several ways for creating a native SQL query:

[1] If your table column names match the ones in your model object, then you could write your query like this:

String sqlQuery = "select * from table_name where field = ?";
Query q = entityManager.createNativeQuery(sqlQuery, ObjectEntity.class);

Here your ORM will automatically populate your ObjectEntity bean with all the corresponding field values from the retrieved database result set. It's important that every field name in your bean class exactly corresponds with the table's column names.

[2] If your table column names differ from your bean's field names, then you'll have to specify a mapping. When using the EJB QL this mapping is done for you by the underlying ORM. You'll have to specify this mapping using the javax.persistence SqlResultSetMapping annotation:

@SqlResultSetMapping(name="MyMappingName",
   entities={
       @EntityResult(name="package.ObjectEntity", fields = {
           @FieldResult(name="id", column="table_column_id"),
           @FieldResult(name="date", column="table_column_date"),
           @FieldResult(name="area", column="table_column_area")
       })
   }
)

"MyMappingName" is a unique name identifying the mapping declaration. The EntityResult annotation declares the particular bean to be populated with the database query data. Every nested FieldResult annotation maps a bean field name to its corresponding column name. The bean's field names are declared using the "name" property, while the "column" property declares the column name. Then instead of specifying the bean class you specify the mapping name within your native query like so:

String sqlQuery = "select * from table_name where field = ?";
Query q = entityManager.createNativeQuery(sqlQuery, "MyMappingName");

[3] Today I experienced a different problem. What if you'd like to populate a bean's fields with the query result, but the bean itself is not managed by the ORM. For scenarios [1] and [2], the assumption was made that ObjectEntity.class is a managed object (declared with an @Entity annotation or within the XML persistence configuration file). Hibernate provides for such a scenario with the ResultTransformer method. The data can be mapped and populated to the ObjectEntity bean using this format:

session.createSQLQuery("select id, date, area from table_name")
.setResultTransformer(Transformers.aliasToBean(ObjectEntity.class))

However, (as I discovered today), standard EJB QL doesn't support a transformer like Hibernate does. In that case one would have to resort to populating the data oneself. The results of a native query is just an Object[]. Every column value is added sequentially in order (as indicated by the select statement) repeatedly for each row. To retrieve the data iterate over the result list, cast the individual column values to their respective types and use it to populate a new ObjectEntity for every new row:

String sqlQuery = "select * from table_name where field = ?";
Query q = entityManager.createNativeQuery(sqlQuery);
List resultList = q.getResultList();

// Declare a list for holding the rows of ObjectEntityData
List listOfObjects = new ArrayList();

// Iterate over the resultList using an Iterator
...
while( iterator.hasNext() ) {
     Object[] columns = iterator.next();
     ObjectEntity objectEntity = new ObjectEntity();
     Long idValue = (Long) columns[0];
     objectEntity.setId(idValue);
     ...
     listOfObjects.add(objectEntity);
}

That's it ! Now you can bypass the ORM alltogether for extracting data into your system.
NOTE: The code i've written here wasn't tested and might contain syntax errors, but the principle works.

Abstract Factory Pattern

2008-09-15T10:20:00.000-07:00

As my first September post I've decided to write a bit about the Abstract Factory.
Remember from the previous posts that the main idea of a reusable object is to capture your dynamic content. In the case of the Abstract Factory, the dynamic component might not seem obvious at first.

It helps to compare this pattern to an "actual factory" e.g. a car factory. The factory produces cars and these cars may be grouped into categories (or products if you'd like). However, each category may consist of several versions of the "same" car (a different colour, different sound system, special add-ons), all tweaked and modified to fit a client's specific needs. Every car is built similar with four wheels, similar framework, and using the same materials.

The same principle applies in software development. You might need to produce the same component (e.g. a window, scrollbar or a panel), but would like to have each component BEHAVE or LOOK differently on different platforms or situations (each one customised to fit the client's specific needs).

The Abstract Factory is abstract, which implies that the actual behaviour or cosmetics is delegated to its implementation. The idea of the Abstract Factory pattern is to have the client code call a particular Concrete Factory implementation to produce the desired components. Each factory might produce windows, scrollbars and panels with a specific theme (e.g. one might produce grey windows while another creates windows that are blue). You end up having several Concrete Factories; each one adding its own touch to the products it produces.

At first you might be tempted to use the Decorator pattern, but this pattern is more usefull in encapsulating extending functionality. It wraps over an existing object and adds more functionality. This could prove to be a better solution than simple subclassing in some scenarios, but the Abstract Factory scenario is different.

A situation might arise where we would like to choose between several of these decorated objects (each one having just a small difference from the other). This would imply an explosion of objects that all look the same, act the same and are used in the same way. Instead of a complex system with thousands of objects, we could try to encapsulate the dynamic component which in this case is the small difference between the various object types or products (e.g. the colour difference between the different types of windows, scrollbars or panels). That is where the Abstract Factory pattern becomes usefull where each Concrete Factory produces its own family of products all using the same theme or colour schema.

Some tips for using this pattern. Use an Abstract Factory:

[1] When decoupling is needed between your system and some individual products. How the underlying components or products are created, composed and represented becomes independent of system behaviour. The system only interacts with abstract interfaces to the underlying components.

[2] When the small differences (e.g. colour) are existent between entire families of products.

[3] When the family of products is designed to be used together (because they're all using the same theme for example).

[4] When you'd like to provide a library of products, but just reveal their interfaces and not their implementations to the system.

Usually the Concrete Factory is instantiated as a singleton (since only one factory is required for every family). The individual products are instantiated using the factory itself and doesn't care whether the factory is a singleton or not. This is analogous to several cars produced in the same car factory (having only one factory doesn't mean you're obliged to produce only one car). On the other hand, you might have several different factories (Mercedes, BMW etc.) each producing their own "families" of cars.

The main point is this: use an Abstract Factory to produce entire families of products or components with some special attribute that distinguishes them from the other families.

EL Functions, Tag Files, Custom Tags and TLD's

2008-08-08T12:03:00.000-07:00

When adding dynamic behaviour (using tags) to your JSP pages,
you'll probably come across 1 of 3 different techniques:

EL functions: When you'd like to perform some simple algorithm function using Java.

Classic Custom Tags: Really old school. Rather make use of JSP 2 Simple Custom Tags if possible

Simple Custom Tags: Gives a little more power over EL functions. Like making use of the body content within the tag and customising the tag's behaviour.

It's always a good idea to create a TLD (tag library descriptor) whenever creating your new tag.
I think of the TLD as: the thing that "describes" the behaviour of your tag to all your other components.

An EL function, is like invoking a Java function that would return a String value. The String result is then printed to your JSP page using the JspWriter. E.g. say you'd like to invoke a Java function that will return a given string attribute in upper case. Then your Java function might look like so:
// imports and package declaration here public class StringManipulation { public static String toUpperCase( String stringToModify ) { return stringToModify.toUpperCase(); } }
One thing to note, is that the Java function for your EL Function has to be public and static, or you'll get compilation errors. Why static ? Well ... think of it this way. You're using an EL function, which means you'll call it just like any other EL as: ${value}. You're simply exporting a value, and by creating a new object instance for every call, would just be unnecessarily computationally expensive.

The next step is to describe your new functions' behaviour in the TLD.
<taglib ... > <tlib-version>1.0</tlib-version> <function> <name>upper</name> <function-class>pckname.StringManipulation</function-class> <function-signature>java.lang.String toUpperCase( java.lang.String ) </function-signature> </function> </taglib>
But, there's more. You might be moving your TLD around ... and besides, how will you be able to uniquely identify your tag from all the other millions of tags in the world ... ? Mmm ...

That's where the use of a URI (Uniform Resource Identifier) comes into play. Have you noticed that every URL (Uniform Resource Locator) you type into your browser is unique. Well it had to be, otherwise which HTML page would be displayed ? So it's safe to say, that every URL is unique, but what about a component name ? Is it possible to declare a universally unique name for your function ? Well, that's exactly what the URI is used for, and usually it takes on the format of a URL (since the URL is unique of course).

This tag mapping must be defined in your deployment descriptor (web.xml).
<web-app ... > ... <servlet> ... </servlet> ... <taglib> <taglib-uri>http://pckName/StringFunctions</taglib-uri> <taglib-location>/WEB-INF/pckName/StringFunctions.tld</taglib-location> </taglib> ... </web-app ... >
Now, all you need to do, is to import your tag's TLD using the specified URI in web.xml,
and then you can use it !
<%@ taglib prefix="myPrefix" uri="http://pckName/StringFunctions"%> ... ${myPrefix:toUpperCase(param.stringToModify) }
URI's can be classified into 3 different categories:

Absolute URI: Has a protocol, hostname etc. E.g. "http://www.whatever.com"

Root Relative URI: Starts with a '/', and is interpreted as relative to the document root. E.g. "/myLibrary"

Non-root Relative URI: Doesn't start with a '/', and is interpreted as relative to the current JSP page or WEB-INF directory (depending on its location). E.g. "myLibrary".

Custom tags and EL functions have many similarities, other that with custom tags you're able to do more. You've got more control over the tag's life-cycle and how it deals with any "body-content", in between the opening and closing tag definitions.

Whereas, the EL Function had a corresponding Java (public and static) function, a custom tag has a Java tag handler. This tag handler is where you'll write your Java code to perform whatever you'd like your tag to do.
The TLD of a EL Function only required a "taglib-version" and "function" declaration. A custom tag must specify it's unique URI name, and a "tag" element. Rather than describing function behaviour as with EL Functions, here we describe tag behaviour instead. In this case, we can declare the behaviour of several tags with the same prefix, within a single TLD.
<taglib> <tlib-version>1.0</tlib-version> <jsp-version>2.0</jsp-version> <short-name>prefixForTags</short-name> <uri>http://www.whatever.com</uri> <tag> <name>aSpecificTagName</name> <tag-class>pckName.TagHandlerClassName</tag-class> <body-content>tagdependent</body-content> <description>Accepts body content within tag as normal text. Performs some function as well.</description> <attribute> <name>user</name> <required>false</required> <rtexprvalue>true</erexprvalue> </attribute> </tag>

body-content: Describe what body-content is allowed to be present between the opening and closing elements of your tag. 'empty'- No body content allowed. 'JSP'- Body content is treated as normal JSP code. 'tagdependent'-The body content is treated as normal text.

required: Describes that this attributes' name-value pair must be declared when using the specified tag element.

rtexprvalue: Describes that the value specified for the underlying attribute. It must be a literal (false) or may be a dynamic value as well (true).

Depending on the particular Tag interface you're implementing,
you may be required to implement the following in your tag handler:

Setter methods for your tag's attributes.

doStartTag() method, executed as the beginning of your tag element declaration. Here you can specify any initialization code for your tag-handler. A return value of EVAL_BODY_INCLUDE says that the body content of your tag must be evaluated, and its output included in the response. A return value of SKIP_BODY says that the body content must not be processed.

doAfterBody() method (if implementing the iteration or body tag interfaces). It gives the tag handler to evaluate the body content again, only AFTER the first iteration. Can return EVAL_BODY_AGAIN to process the body content again, or SKIP_BODY to go on to the end of the tag. If implementing the body tag interface, EVAL_BODY_BUFFERED allows you to pre-process the body content, before anything is written to the response.

setContentType() method (if implementing the body tag interface). The JSP container calls this method to pass an instance of the body content to the tag handler.

doInitBody() method (if implementing the body tag interface). The container calls the doInitBody() method AFTER the setContentType() method, and allows the tag handler to initialize the body content object passed to it.

doEndTag() method is the last method that executes before the tag processing exits. Here you can specify whether the rest of the JSP page should be evaluated EVAL_PAGE, or should be skipped all together SKIP_PAGE.

The Simple Custom tag is very similar to the Classic Custom tag, except that instead you're only required to override a single method called "doTag()". For your simple tag handler, you must implement the SimpleTag interface. The
interface in return extends the JspTag interface. The JspTag interface was added in JSP 2, so that simple and classic tags could work together. See ... the JspTag is the "SUPER" interface for both simple and classic tags, so we could make use of polymorphism and use both tag types in the same JSP. But why are there 2 different types of tag handlers ? Well ... my guess is that SUN initially made a little of a mistake, by not allowing one to edit/process the body content of a tag at first. Making use of the body tag just added more complexity to the entire process, and the Simple tag method fixed it all.

In fact, to pre-process the body content using a simple custom tag is simple. Only call the getJspBody() method to get the body content of the tag, and then you'll be able to process the content.

Anyway, the life-cycle steps for a simple custom tag goes something like (in chronological order):

setJspContext(JspContext): Makes the JspContext available during tag processing.

setParent(JspTag): Sets any parent tag of this tag, if available.

setXXX(...): Then sets all your specified attributes into the tag handler.

setJspBody(JspFragment): Makes the body content of the tag available for processing.

doTag(): This invokes your customised doTag() Java method.

The TLD for the simple custom tag looks the same as a TLD for a classic custom tag.

To write the body content of a simple custom tag to the output simply call getJspBody().invoke(null);. The invoke method requires an argument specifying the JspWriter that will receive the JspFragment's output. If 'null' is specified, then the output is directed to the JspWriter returned by getJspContext().getOut(), and is then written directly to the response. To alter the body content, you could also pass in your own java.io.Writer, and use that to gain direct access to the body contents.

Finally, there's also something called tag files that you may use. A tag file is made up of JSP code that has a .tag or a .tagx extension. The only elements that CANNOT be used in tag files are page attributes. With tag files no Java or TLD files are involved, except if the tag resides in a JAR (then a TLD is required). This is because, the container is only required (by specification) to look under the /WEB-INF/tags/.. directory, in order to find a tag file.

To integrate tag files into a JSP involves 2 steps:

Add a taglib directive to the JSP page with a prefix attribute and the tagdir attribute, indicating where your tag file resides (must be under /WEB-INF/tags/ ...).

Use the tag wherever on your page, containing the prefix and the name of the tag file.

What happens, is that the container searches for the specified tag file in the tagdir directory. After the container finds the tag file it automatically builds an implicit tag library and TLD for this directory and each subdirectory beneath it.

If a tag resides in a JAR, then the tag file must reside under /META-INF/tags, and a relating TLD MUST be created. Below is an example of a TLD for an archived tag file:
<taglib> ... <uri>www.whatever.com/example</uri> <tag-file> <name>example</name> <path>/META-INF/tags/example.tag</path> </tag-file> </taglib>
In this case, you cannot use tagdir to locate the tag file to be used inside the JSP. Instead you'll need to specify the tag file location, using its URI, as in:
<%@ taglib prefix="ex" uri="www.whatever.com/example" %>
Your tag file is just normal JSP code. So you could liken it to the include page directive, if you'd like. However, it's a little different than a normal file inclusion. With tag files, you can specify attributes that are objects, other than request parameters which are just String values. Since we don't always need to declare a TLD for tag file, how would it know what its attributes are, and how will it retrieve them ?
To retrieve attributes you must specify an attribute directive in your tag:
<%@ attribute name="myAttribute" required="true" %>
OK ... so you now know more about the tags available at your disposal. But how do you decide which one to use, and when ?

My philosophy is so. If you just like to set data or get data, then rather use EL or Java beans, but if you're going to have to do some Java processing on your data, then custom tags are the way to go. If instead, you're algorithm for data processing is rather simple, and doesn't require complex interaction with the presentation layer, a simple EL function should do the job. Finally, if you're requirements are primarily on manipulation on the presentation layer (such as CSS or some other container elements), then make use of tag files, it will save you development time, effort, and in my opinion is the easiest to use of them all.

So that was just a little primer about tags. They can be very useful if used appropriately.
Enjoy !!

Design Patterns: The STRATEGY pattern.

2008-08-08T09:53:00.000-07:00

The strategy pattern is a way of thinking, a plan of action. Whether you might know it or not, you've probably implemented it already in some past project of yours :)

I'll suggest going about like so:

Classify your project up in parts. Try to identify the things that are more dynamic (the things that change more frequently in your application). Then identify the more static parts.
If some group(s) of your dynamic parts/components have something in common, well then you might have an opportunity to employ the strategy pattern !!

Your strategy is the "interface" defining the common things in the group you've just made (step 2).
By encapsulating the dynamic parts of your application into objects, you'll be able to break the inheritance layer structure. I've recently found that if you've got a heavy layered structure, consisting of several layers build on top of one another, re-factoring becomes a pain (TDD/XP). In that case consider the strategy pattern as a good alternative.

Instead of your interface build on layers upon layers of code, try delegating objects to do the particular task for you. Inject them into your structure and see your overall structure being simplified.