Part 1 – Business Value, Smells, and an adoption Strategy

This part of the book focuses on the reasons why one might consider adopting agile practices.  It starts by looking at the value that agile practices can bring to the business, follows on by suggesting problems that agile practices could address and finishes by describing how to adopt agile practices.

Business Value

Agile practices have the potential to deliver value to the business in a number of areas and your business might be more sensitive in one or more of these areas.  The areas discussed include:

A useful exercise is presented at the end of this section to help one determine which areas are more important to your business.

Smells

We, as developers, are used to discussing code smells but probably less used to discussing smells in our development methodology or practices.  This section discusses “Business smells” and “Process smells”.  Business smells are smells that affect the business and are visible to customers while process smells are only visible to the development team.  I’ve listed the smells discussed below:

Business Smells

Process Smells

Again, a useful exercise is presented at the end of the section that asks one to discover, investigate and rank smells within the organisation.

Adopting Agile Practices

An awareness of agile practices is assumed as business values are related to corresponding agile practices that could potentially enhance the ability to deliver these values.  Similarly, smells are related to corresponding agile practices that could potentially address the smell.

Advice is then delivered on how to use the information presented to develop a tailored agile adoption strategy.  This advice can be summarised as follows:

Part 2 – The Patterns

As with any pattern language, the patterns presented adopt a standard layout.  The layout presents:

Automated Developer Tests

This pattern describes a set of tests that are maintained by developers to reduce the occurrence and/or cost of bug, increase confidence when refactoring and increase decoupling.  The tests are then executed automatically as part of a continuous integration process.

Test-Last Development

This pattern describes writing automated developer tests after the code has been written.  Tests tend to conform to the initial implementation rather than the requirements (if they differ).

Test-First Development

This pattern describes writing automated developer tests before the code has been written.  Testing in this way is more effective than Test-Last Development but harder to adopt.  Tests conform to the requirements as no code exists.

Refactoring

This pattern describes changing the structure of code without changing the behaviour.

Continuous Integration

This pattern describes the practice of performing a clean build, deploy and execution of unit and integration tests every time a code change is committed to the source repository.

Simple Design

This pattern describes resisting over engineering a solution and extending a design only when required.  Add more flexible\complex designs only when needed to avoid the cost of complex software until the benefit is necessary.

Functional Tests

This pattern describes executable requirements that can be used as functional tests.  These functional tests represent the requirements of the user and when complete indicate the requirement is done.  Some useful examples are provided to clarify what functional tests are.

Collective Code Ownership

This pattern describes code ownership where no one individual or set of individuals has exclusive ownership of a section of the code base.

Part 3 – Clusters of Practices

Clusters, as described in this book, are groups of agile practices that build upon or complement each other such as the cluster of practices are greater than the sum of their parts.

Evolutionary Design

This cluster describes a set of practices that support an evolutionary design process.  These practices include Automated Developer Tests, Refactoring and Simple Design.

Test-driven Development

This cluster describes a set of practices that focuses on developer tests.  These practices are primarily Evolutionary Design, Collective Code Ownership and Continuous Integration.  The primary practices in turn include others resulting in the inclusion of many of the practices described.

Again the sketch is very useful in that it narrates a very real illustration of adopting this cluster of practices.

Test-driven Requirements

This cluster describes a set of practices that focuses on testable requirements.  These practices are Functional Tests, Customer Part Of Team and Continuous Integration.

Thoughts

The first part of the book deals with the first problem when trying to adopt agile practices and that is to get buy in from the stakeholders.  What is the business getting from this transition? What are the business owners getting?  What are the developers getting?  All questions that need to be answered before you can start to transition to agile practices.  The transition is not an easy one and so you will need committed stakeholders.

The section on smells relates the problems that the business is experiencing to those of the development teams and vice versa which is really useful in clarifying possible cause and effect.

I recently read The Pragmatic Programmer and I like the way the material presented similarly to a pattern language i.e. short, concise and well organised.  Presenting them as patterns also leads a developer familiar with patterns to understand how they can be applied, as guidance rather than absolute right or wrong.

The “Sketch” narrative in the patterns section enhances the understanding of the pattern.  I like this story telling approach and it is similar in style to the Kate Oneal stories by Ron Jefferies.

The difficulty of non-consistent architecture when applying evolutionary design is very real and although it is addressed in the book, it is a problem that will always be difficult to address.  Communication and collaboration can be the key but then you have the potential problem of too much communication.  The “Divide After You Conquer” technique is one I have seen work well in the past and this is the approach I would tend to take.

“Domain Driven Development Quickly” is a book from InfoQ that summarises the material presented in Eric Evans’ Domain-Driven Design book.  It can be downloaded freely in PDF format (requires registration).

Chapter Summary

What is Domain Driven Development

An introduction to domain driven development is presented by first discussing the general nature of software development.  An example and discussion of the solution domain follows.

The value of reflecting the (abstract) business domain in code is discussed.  An overview is provided of how the model is developed from initial discussions with domain knowledge experts.  A high level explanation of how the domain model evolves and is used to convey knowledge among interested parties is then given.

The Waterfall Model receives some criticism because of the absence of a feedback loop from business expert to analyst to developer.  Agile methodologies on the other hand receive praise for their iterative nature.

Finally, a worked example of building a domain model for a flight control system is presented. The role of the software modeller and knowledge expert is described as is their interaction during the development of the domain model.

The Ubiquitous Language

This chapter begins by describing the need for a common language through which the software and knowledge experts communicate.  The domain model is described as the basis for this common language as it is the place where software meets the domain.  This language is known as the Ubiquitous Language because it is the common language used for all communications related to the project.

An approach to creating a language is described through a hypothetical dialog between a software developer and a domain expert in the flight control system project.  Mechanisms to document the domain model include UML and it is recommended that non-trivial domain models are captured in many smaller UML documents with annotations where appropriate.

Model-Driven Development

Sometimes difficulties occur in translating a domain model into a model that can be implemented in code.  For this reason it is advised that the developers participate in the domain modelling process to ensure that the domain model can be implemented in code and is consistent with that derived during analysis.

The most important patterns for model driven design are covered and include the following;

Layered Architecture

This pattern advocates partitioning a complex program into cohesive layers, specifically User Interface, Application Layer, Domain Layer and Infrastructure Layer.

Entities

This pattern illustrates the use of objects that maintain a consistent and universal identity throughout the system.

Value Objects

A Value Object is described as an object that is used to describe certain aspects of a domain but that does not possess an identity.  Value Objects are often immutable.  Money is a common example of a Value Object.

Services

A Service is described as an object that contains functionality that is exhibited by the domain but not easily mapped to objects.  An example is given of a money transfer between two accounts; does this behaviour belong in the sending or receiving account?

Modules

Modules are a way to organise related concepts in order to reduce complexity.

Aggregates

“An Aggregate is a group of associated objects which are considered as one unit with regard to data changes.”  An example of a Customer and Address is given were the Address is immutable and changes are made through the Customer e.g. customer.setAddress(String line1..).

Factories

A Factory encapsulates complex creational functionality allowing clients to create Aggregates without exposing the construction mechanism.

The Factory Method and Abstract Factory patterns are review from the perspective of domain modelling.

Repositories

Repositories are objects used to obtain references to Entities, usually from a database or another persistent data store.  The Repository interface will be pure domain model and so should not imply a specific persistence store.

Refactoring Toward Deeper Insight

This section begins by discussing refactoring the domain model when new concepts or insight occur.  It then goes on to talk about breakthrough moments when a significant (in terms of understanding) change is required to the model.  Breakthroughs occur generally when some implicit knowledge becomes explicit and this occurs naturally when exploring concepts with domain experts.  They can also occur when contradictions are highlighted or through reading material on the domain.

The usefulness of making the Constraint, Process and Specification concepts explicit is also discussed.  I particularly like the Specification concept which is used to test an object to check if an object satisfies certain criteria.

Preserving Model Integrity

This section deals with preserving the integrity of the model when a project involves large or multiple teams.  The model can become disjointed and the consistency of the model can suffer.  The suggested solution is to create several independent modules that are well integrated.  This allows each model to evolve, as long as it adheres to its contract, and the interaction between models to remain unaffected.

A number of techniques to help maintain model integrity are presented as follows:

Bounded Context

The bounded context defines a specific meaning for each model and the language used within.  The meaning is used consistently within the model and by other models interacting with the model.

Continuous Integration

Continuous integration suggests frequent build and test cycles to detect inconsistencies between interdependent models.

Context Map

This extract from the book describes this concept very concisely: “The context map is a document that outlines different bounded contexts and the relationships between them.”

Shared Kernel

A shared kernel is a model sub-section that is shared between multiple models.

Customer-Supplier

Customer-supplier describes a relationship between two models when one model utilises another significantly.

Conformist

Conformist describes when a supplier has no motivation to evolve a model in collaboration with a customer and so the customer must conform to all changes in the supplier’s model.

Anticorruption Layer

The anticorruption layer is a subsection of a model that is consistent with the model but represents concepts from and interacts with another external model.

Separate Ways

Separate ways describes what happens when the benefits of integrating two models are outweighed by the cost.  The two models diverge and cease to maintain any commonality.

Open Host Service

Open host service describes when a single supplier model is utilised by multiple customer models using a single common interface.  The interface is expanded and refactored to meet the needs new integration requirements.

Distillation

Distillation is the process of talking a large domain model and extracting the essence of the model into a core domain model.  Elements of the model that do not form the core domain model will be captured in generic sub-domains.

DDD Matters Today: An Interview with Eric Evans

An interesting interview with Eric Evens is included at the end of this book.  The interview is best distilled by presenting the questions of the interviewer.  They are as follows:

Why is Domain Driven Design as important today as ever?

Technology platforms are continually evolving.  How does Domain Driven Design fit in?

What’s been happening in the Domain Driven Design community since you’ve written your book?

Do you have any advice for people trying to learn Domain Driven Design today?

Thoughts

I like the emphasis placed on developing the Ubiquitous Language and totally agree with its value to a project in creating a common vocabulary.

I agree with the vast majority of the material but I’m not sure that I agree with the suggestion that a repository interface should use a “Specification” to define complex criteria for Entity search.  More often than not, the specification tempts developers to couple data access knowledge to the Application Layer.  I see this as similar to using criteria queries defined within the Application Layer and in my opinion this breaks encapsulation.  I much prefer strongly typed search interfaces with methods such as findActiveByName, findByColourAndLength etc.  I guess I could accept the Specification approach if the Specification deals with pure domain model (i.e. Entities and/or Value Objects) and does not have pseudo JPA SQL.

The interview with Eric is excellent and if you don’t have time to read the entire book I would recommend at least reading the interview.  The answers were insightful and provided a good summary of the past and future of domain driven development.

Overall, there is much to take away from this book and I will certainly be focusing more on trying to apply some of the concepts, in particular the Specification concept.  It’s a no-brainer to read this book.  It is full of relevant, current and well presented material.  It is freely available and is a good investment of time.

Ron Jefferies said about this book “As with any such book, much of the advice is something you already know. Much of it is also something you have forgotten to focus on lately.” You may or may not learn anything new, but this book will remind you what is important.

Chapter Summary

Chapter 1 – A Pragmatic Philosophy

“Software Entropy” is compared to the “Broken Window Theory” and some causes and consequences are discussed.  This is a very useful analogy and comparable to technical debt as used by some agile methodologies.

The knowledge portfolio is a very useful concept and it never ceases to amaze me how little software “professionals” invest in their development.  Join a “big 4” accountancy firm and you will be mentored through an intensive training programme; medical and legal professionals are required to earn “continued professional development” (CPD) points and yet some software developers aspire to be considered “professional” without “Investing in their Knowledge Portfolio”.  It’s not all one way though; the knowledge portfolio needs to be valued more by those employing software “professionals”.

One of the sentences that stood out when discussing communication was the following: “This isn’t communicating: it’s just talking, and it’s annoying”.  How true this is and it’s the role of a strong meeting facilitator (Scrum master etc.) to ensure that participants are communicating and not just talking.  The same goes for email groups and so many things besides.

Chapter 2 – A Pragmatic Approach

“The Evils of Duplication” highlights the areas were duplication can (and does) occur, the consequences and how to best avoid duplication.  This includes requirements and design documentation as well as code.

The recommendation to have in built “Reversibility” not only reinforces the OO principles of encapsulation and programming to interfaces but goes further by suggesting that these be applied at an architectural level.  Of course this process has a limit and some decisions will always be difficult to reverse.

“Tracer Bullets” are described as end-to-end implementations of a subset of functionality that is built upon to deliver the complete solution.  I guess this is similar to what is often referred to as “spikes” except that Tracer Bullets are incorporated in the complete solution.

The use and abuse of prototypes are discussed along with some decisions to make when considering prototyping.  The choice of using “Tracer Bullets” as opposed to prototypes is also covered.

Tips and techniques for estimating are explored along with some insightful thoughts on how people interpret estimates.  For example, an estimate of 16 weeks or 4 months is the same (approximately) in terms of duration but the latter suggests a greater degree of uncertainty.

Chapter 3 – The Basic Tools

Stepping out of the IDE used to be something that every developer did frequently.  Now it is less common and we are reminded of the power and flexibility of shell commands.

Source control systems have evolved significantly over the past few years and we are reminded why we use source control and where its value lies.  Useful stuff if you are trying to make a case to move away from your current source control system.  While migrating source can be challenging, I’m often surprised at the inertia in this area when the benefits are substantial.

In football, commentators often talk about “playing the percentages” and this concept is used to discuss debugging and root cause analysis.  Look in the most likely places first (i.e. your own code) and you will find bugs faster.  The tendency to point somewhere else must be overcome.  Other useful practices such as feeding bugs back in to regression testing are discussed.

Code generation is discussed and importantly how it violates the DRY principle to check in code generated by active code generators.  This is something I see often and it is normally accompanied by some justification.  With the flexibility and power of today’s build tools, I feel there is no justification for checking in actively generated code.

Chapter 4 – Pragmatic Paranoia

Design by contract (DBC) is introduced in the context of method contracts.  Of course, these days when DBC is discussed we are usually referring to web services but more fundamental is the contract of our methods.  Assertions are a good tool for enforcing method contracts and some of the subtleties of using assertions are discussed.

The other sections on exceptions and resource management are probably well known to most nowadays as there is a greater awareness of these subjects.

Chapter 5 – Bend, or Break

Coupling is explained and a description of using the Law of Demeter to reduce coupling for functions is given.  It was interesting to have this laid out in black and white.  The sort of knowledge one should absorb and apply without thinking (although it’s useful to work through the thought process).

The benefits of meta-data driven programming are extolled although again I would say that programmers are more aware of this type of programming and the trade-offs that at the time the book was written.

Temporal coupling (as pointed out by the author) is often forgotten, or not given enough focus (even in today’s world of multi-threaded, distributed systems) during system design.  A solid understanding of the temporal coupling within a system will make opportunities for improved concurrency more visible.

The Model-View-Controller pattern, Observer pattern and Publish-Subscribe paradigm are discussed in the context of reduced coupling.  Additional reading is necessary for the reader to fully grasp the concepts being presented.

Blackboards or shared-spaces are discussed along with their potential to reduce coupling.  I recently took an agent oriented programming course so this material was very familiar.

Chapter 6 – While You Are Coding

I found the first paragraph in this chapter very striking as I have had many experiences that reinforce the point.  This paragraph states:

“Conventional wisdom says that once a project is in the coding phase, the work is mostly mechanical, transcribing the design into executable statements.  We think this attitude is the single biggest reason that many programs are ugly, inefficient, poorly structured, unmaintainable, and just plain wrong.”

The emergence of Agile methodologies has gone some way to increase the awareness of this point by pushing design closer to implementation but this problem has not gone away.

An overview of how to estimate algorithm speed is provided and some guidance is provided to apply these techniques.  As is stated, this is not something that most developers have to be overly concerned about but all should have an appreciation and awareness of the effect different algorithms can have on performance.

Refactoring and unit testing are then discussed.  Developers are a lot more aware of these subjects than when the book was originally written but nevertheless the sections provide a useful refresher.

A section on wizards or “Evil Wizards” describes the potential hazards of using wizards and adopting code that you may have little understanding of.

Chapter 7 – Before The Project

Pragmatic approaches to determining and documenting requirements are discussed along with some common mistakes.

“Solving Impossible Puzzles” encourages use to take a step back, look at the puzzle we are trying to solve, try to solve it in other ways or perhaps it is not a problem we need to solve after all.

“Circles and Arrows” reminds us to take what is useful from formal methods and leave behind those things that are not.

Chapter 8 – Pragmatic Projects

Previous techniques are revisited with a focus on how their characteristics change when applied to a team of programmers.

Automation is then covered in some detail including code/documentation generation as well as automated build, test, coverage etc.

“Ruthless Testing” encourages programmers to think about the value of testing, add tests that are valuable and test the tests.  When a bug slips through the net test suits should be enhanced to reduce the chance of future occurrences.

“It’s all Writing” outlines the importance of writing documentation in a way that adheres to the DRY principle and that follows the same pragmatic approach taken when writing code.

Thoughts

Each section describes a pragmatic practice that one might adopt in an attempt to improve working practice and performance.  In the foreword by Ward Cunningham, Ward compares the presentation of the material to that of pattern languages.  This is because each section is described concisely with “Related Sections” and “Challenges”.  This worked out great for me because I want bite sized nuggets of information to read on my daily commute.  I am never forced to put the book down in the middle of a section as they are short enough to read quickly and independent enough that they can be read in any order.

As with its follow up ‘Pragmatic Thinking & Learning’, ‘The Pragmatic Programmer’ is littered with relevant quotes.  Again, I have highlighted some of my favourites below:

Benjamin Franklin, “An investment in knowledge always pays the best interest.”

Mae West, “I believe it is better to be looked over than it is to be overlooked.”

Emil-Auguste Chartier, “Nothing is more dangerous than an idea if it’s the only one you have.”

Woody Allen, “When everybody actually is out to get you, paranoia is just good thinking.”

Ralph Waldo Emerson, “Nothing astonishes men so much as common sense and plain dealing.”

If you want to read a book that just makes sense then this is the book you have been looking for.  You will find yourself repeating “how true” over and over again until the point when you ask “This stuff is so obvious.  Why have I not thought of this before and why are we not acting upon it.”  Well here is your chance to redeem yourself; pick up a copy, read it, then apply it.

Chapter Summary

Chapter 1 – Introduction

The context for the book is set and importantly, Andy highlights that while this book discusses the material and techniques with a focus on programming, it is not specific to programming.  Indeed, I purchased the book hoping to improve the effectiveness of my studying techniques generally and the techniques covered have wide applicability.  Andy also summarises the material and how it will be presented.

Chapter 2 – Journey from Novice to Expert

The five stages of the Dreyfus model of Skill Acquisition are explored.  Examples of how the Dreyfus model can be used (and abused) are presented in the section “Herding Racehorses and Racing Sheep”.  It’s a very useful title in that it invokes a strong image of poor utilisation of specialised resources.

Chapter 3 – This is Your Brain

The nature of human learning is explored and distinctions are made between the “left-brain” (L-mode) and the “right-brain” (R-mode).  Andy describes L-mode thinking as the process of linear thinking that provides us with analytic, rational and logical abilities.  He describes R-mode thinking as the process of rich thinking that provides us with synthetic and intuitive abilities.  Andy describes the importance of both modes of thinking and how to stimulate both, paying particular attention to R-mode given that it provides functions important to the expert practitioner.

Chapter 4 – Get in Your Right Mind

Techniques for engaging the “right-brain” are explored along with which mode is appropriate to which activity.  Often, to accomplish a goal both modes are required and this is demonstrated by a story about rock climbing that was particularly appropriate.

Chapter 5 – Debug Your Mind

Further insight is given into how we think, the processes we undertake and the flaws (or features) of our thought process.  “To be forewarned is to be forearmed” and so to be aware of the flaws in our thought process is to impart the ability to compensate for such flaws.  One such flaw was that of anchoring which was demonstrated during a lecture I recently attended.  A group were asked to write down an estimate for a piece of work and then asked to call out the estimate to the group.  It was demonstrated that people altered their estimate as others in the group made their own estimate known.  The discussion on generational affinity was also very insightful and very easy to relate to my own experience.

Chapter 6 – Learn Deliberately

Applied techniques to learning are described including SMART objectives, Pragmatic Investment Plans, study groups, SQ3R (Survey, Question, Read, Recite, and Review) and Mind Maps.  Andy also describes how he personally uses these techniques and what he feels works well.

Chapter 7 – Gain Experience

The famous catch 22 situation of needing experience to attain a role that provides experience comes to mind.  Other methods of gaining experience are discussed along with which experiences are more important than others.  Andy then discusses how to approach learning through exploration and the importance of learning through mistakes.  This includes the characteristics of an environment that facilitates this type of learning (source control etc.).  The advantages and disadvantages of leveraging existing knowledge to attain new knowledge are covered.

Chapter 8 – Manage Focus

The importance of maintaining focus and the cost of switching focus are explored.  Practical techniques to reduce interruption are introduced.  Techniques range from meditation to simple things like managing desktop and telephone (IM, internet…) interruptions.  Project teams rules of engagement are introduced as rules to reduce interruptions within project teams.

Knowledge management techniques such as wiki’s etc are discussed with reference to how Andy uses such techniques to develop his own knowledge and ideas.

Chapter 9 – Beyond Expertise

A parting note from Andy on possible next steps presented as a way to apply the knowledge attained through the book.

Thoughts

The “Next Actions” serve as a very useful prompt to not only read and learn the material but to apply it while it is fresh in your mind (thus reinforcing it).  This is very important with this type of material.

The numerous quotations sprinkled throughout the book encapsulated the essence of the material and planted a seed of thought from which to explore the material more thoroughly.  Here are some quotes which I found particularly relevant:

John Muir: “When we try to pick out anything by itself, we find it hitched to everything else in the universe.”

Albert Einstein: “We can’t solve problems by using the same kind of thinking we used when we created them.”

Mark Twain: “We should be careful to get out of an experience only the wisdom that is in it and stop there; least we be like the cat that sits on a hot stove-lid; he will never sit on a hot stove-lid again – and that is well; but also he will never sit on a cold one anymore.”

James Joyce: “A man’s errors are his portals to discovery.”

John Anthony Ciardi: “A good question is never answered.  It is not a bolt to be tightened into place but a seed to be planted and to bear more seed toward the hope of greening the landscape of idea.”

While these quotes are insightful to me, I can’t help think that for some, nothing short of writing them on a stick and hitting them on the head will have people consider them in the same light.

I found the anecdotes throughout the book particularly useful in explaining sometimes difficult concepts.  The tips provide suggestions to apply the techniques and are enumerated at the end of the book in a number of tear out cards.

Overall, the book was a good read, packed with practical suggestions of how to apply the material to enhance one’s thinking and learning capacity.

The book chronicles the experience of an engineering team struggling to design and develop a new computer under huge pressure, both internal and external.

This is not the sort of book I would ordinarily pick up and read as I normally find myself reading books on specific technologies, frameworks or methodologies.  I must admit that I enjoyed the book and found that despite being published in 1981, Tracey Kidder’s observations on the way the organisation approached projects and the associated challenges were very familiar.

It was most striking that I have worked with many characters similar to those portrayed in the book.  Kidder’s observations on, and reasoning about, their behaviour was very insightful.  Kidder also focused on how the individual team members collaborated and the intricate personal relationships within the group.

Overall, an extremely interesting case study of people, process and practice and how they interact in a knowledge based industry.

I first got the idea for such a profiling aspect from the Spring Framework user guide which presents a basic implementation in the Spring AOP section.  I subsequently observed a more sophisticated implementation developed by Jerry Kiely, who I occasionally have the pleasure of working with.

In what follows, I will present an implementation of a profiling aspect and explain how this can be utilised using Spring and AspectJ Load Time Weaving.

Task and Task Timer Implementation

The profiling aspect will record the start time and end time of each method invocation thus allowing more valuable statistics to be derived at a later point in time.  To make this functionality reusable, we will develop more abstract TaskTimer and Task implementations.

The Task represents any action for which we require timing metrics and records the task name, start time and end time.

package net.thoughtforge.task;

public class Task {
  
  private Long endTime;
  
  private String name;
  
  private Long startTime;
  
  public Task(String name, Long startTime) {
    this.name = name;
    this.startTime = startTime;
  }
  
  public long getDuration() {
    return endTime - startTime;
  }

  public Long getEndTime() {
    return endTime;
  }
  
  public void setEndTime(Long endTime) {
    this.endTime = endTime;
  }
  
  public String getName() {
    return name;
  }
  
  public Long getStartTime() {
    return startTime;
  }
}

The TaskTimer provides a simple stack based timer implementation that allows one to start a named task, stop a task and obtain a list of all completed tasks.  When a  named task is started, it is pushed onto the stack and when a task is stopped, it is popped off the stack and the end time is set.  The task is then added to a list of completed tasks for futher analysis at a later point in time.

package net.thoughtforge.task;

import java.util.ArrayList;
import java.util.List;
import java.util.Stack;

public class TaskTimer {

  private List<Task> completedTasks = new ArrayList<Task>();
  
  private Long endTime;
  
  private String id;
  
  private Long startTime;
  
  private Stack<Task> taskStack = new Stack<Task>();
  
  public TaskTimer(String id) {
    this.id = id;
  }
  
  public long getTaskCount() {
    return taskStack.size();
  }
  
  public long getTotalDuration() {
    return endTime - startTime;
  }
  
  public String printSummary() {
    StringBuffer summary = new StringBuffer(shortSummary());
    summary.append('\n');

    TaskSummaryVisitor taskSummaryVisitor = new TaskSummaryVisitor(getTotalDuration());
    for (Task task: completedTasks) {
      taskSummaryVisitor.visit(task);
    }
    
    summary.append(taskSummaryVisitor.printTaskSummaries());
    
    return summary.toString();
  }
  
  public String shortSummary() {
    return "TaskTimer '" + this.id + "': running time (millis) = " + getTotalDuration();
  }
  
  public void start(String name) {
    Long startTime = System.currentTimeMillis();
    
    if (taskStack.isEmpty()) {
      this.startTime = startTime;
    }
    
    taskStack.push(new Task(name, startTime));
  }
  
  public void stop() {
    Long endTime = System.currentTimeMillis();
    
    Task currentTask = taskStack.pop();
    currentTask.setEndTime(endTime);
    
    if (taskStack.isEmpty()) {
      this.endTime = endTime;
    }
    
    completedTasks.add(currentTask);
  }
}

The TaskTimer is not an exhaustive implementation (no checks for end of stack etc.) so if you intend to reuse this you should certainly adapt it further.

I notice a JIRA issue requesting that Spring add similar functionaliy to the StopWatch class.

The Profiling Aspect

As with the Logging Aspect, the Profiling Aspect uses the @Aspect approach to defining the aspect, advice and pointcuts.

The first thing you will notice is a ThreadLocal reference to a TaskTimer.  This ensures the method profile metrics from different threads are not interleaved.  It is more that likely that one will want to look at profiling information from a single thread at a time.

The aspect contains a single piece of around advice that creates a task name, starts the task timer, invokes the method and stops the task timer.  This is fairly trivial and the only point of interest to draw your attention to is the point where the profiling metrics are output to the logging system.

Effectively, on completion of the method that initiates the profiling, the profiling metrics will be output to the logging system.  If you consider a Servlet based application you could imagine the profiling beginning on the Servlet service method, and the profiling information being logged on the completion of the service method.

package net.thoughtforge.aspect;

import net.thoughtforge.task.TaskTimer;

import org.apache.commons.logging.LogFactory;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Pointcut;

@Aspect
public abstract class ProfilingAspect {

    private ProfilerThreadLocal profilerThreadLocal = new ProfilerThreadLocal();

    @Pointcut
    public abstract void profilingPointcut();
    
    @Around("profilingPointcut()")
    public Object doProfiling(ProceedingJoinPoint proceedingJoinPoint) throws Throwable {

        String taskName = createTaskName(proceedingJoinPoint);
        TaskTimer taskTimer = profilerThreadLocal.get();
        try {
          taskTimer.start(taskName);

            return proceedingJoinPoint.proceed();
      } finally {
        taskTimer.stop();

        if (taskTimer.getTaskCount() == 0) {
            doLogging(proceedingJoinPoint.getTarget().getClass(), taskTimer.printSummary());
            profilerThreadLocal.remove();
        }
      }
    }

    private String createTaskName(ProceedingJoinPoint proceedingJoinPoint) {
        return new StringBuffer(proceedingJoinPoint.getTarget().getClass().getName())
            .append(".")
            .append(proceedingJoinPoint.getSignature().getName())
            .toString();
    }

    private void doLogging(Class<? extends Object> clazz, String prettyPrint) {
      LogFactory.getLog(clazz).info("\n\n" + prettyPrint + "\n");
    }

    private class ProfilerThreadLocal extends ThreadLocal<TaskTimer> {

        @Override
        protected TaskTimer initialValue() {
            return new TaskTimer(Thread.currentThread().getName());
        }
    }
}

Specifying the Pointcut

As with the Logging Aspect, the Profiling Aspect pointcut expression selects methods annotated with a specific annotation (the Profilable annotation).  This obviously prohibits profiling code which you cannot modify (i.e. add the annotation) so you will probably want to use other criteria within the pointcut expression.

By default, Spring uses proxy based aspect orientated programming (AOP) which limits us to applying aspects to Spring beans (look at the spring documentation for further discussion).  An alternative to proxy based AOP is to use AspectJ Load Time Weaving (LTW) which instruments the code when loaded by the class loader.

To enable LTW, a configuration file (aop.xml) must be placed in a META-INF directory on the classpath.  Within the aop.xml file, the aspect and the classes to be weaved must be specified.  The pointcut expression can also be specified but I will leave this for you to look into.

<!DOCTYPE aspectj PUBLIC "-//AspectJ//DTD//EN" "http://www.eclipse.org/aspectj/dtd/aspectj.dtd">

<aspectj>
  <weaver>
    <!-- only weave classes in our application-specific packages -->
    <include within="net.thoughtforge.service.*"/>
  </weaver>
  <aspects>
    <!-- weave in just this aspect -->
    <concrete-aspect name="profilingAspect"
        extends="net.thoughtforge.aspect.ProfilingAspect">
        
      <pointcut name="profilingPointcut"
          expression="execution(* *(..)) &amp;&amp; @annotation(net.thoughtforge.aspect.Profilable)"/>
    </concrete-aspect>
  </aspects>
</aspectj>

The other thing that needs to be done is to instruct the JVM to have AspectJ perform the LTW when a class is loaded.  To do this specify the following JVM parameter (inserting your own path):

-javaagent:{path-to}\spring-agent-2.5.6.jar

Specifying the spring agent as opposed to the AspectJ agent has some advantages discussed within the Spring documentation.

Testing the Profiling Aspect

In this instance, rather than create a unit test to test the Profiling Aspect, I have created one to demonstrate it in action.  I created a simple service annotated with the Profilable annotation.  Invocations of methods within this service will be profiled and the profiling metrics will be output by the logging framework.

package net.thoughtforge.aspect;

import net.thoughtforge.service.ExampleService;

import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = {
    "/applicationContext/applicationContext-aspect.xml",
    "/applicationContext/applicationContext-service.xml",
    "/applicationContext/applicationContext.xml" })
public class ProfilingAspectTest {

  @Autowired
  public ExampleService exampleService;

  @Test
  public void doSomething() throws Exception {
    exampleService.doSomething();
  }
  
  @Test
  public void doSomethingWithSomething() throws Exception {
    exampleService.doSomethingWithSomething();
  }
  
  @Test
  public void doSomethingWithSomethingFiftyTimes() throws Exception {
    exampleService.doSomethingWithSomethingFiftyTimes();
  }
}

Executing the profiling aspect test results in the following logging output:

TaskTimer 'main': running time (millis) = 109

-------------------------------------------------------------------------------------------------
Invocations  Total Time(%)  Total Time(ms)  Min Time  Max Time  Average Time(ms)  Task Name
-------------------------------------------------------------------------------------------------
00001    100%    00109    00109    00109    00109      net.thoughtforge.service.ExampleService.doSomething

TaskTimer 'main': running time (millis) = 63

-------------------------------------------------------------------------------------------------
Invocations  Total Time(%)  Total Time(ms)  Min Time  Max Time  Average Time(ms)  Task Name
-------------------------------------------------------------------------------------------------
00001    002%    00001    00001    00001    00001      net.thoughtforge.service.ExampleService.getSomething
00001    100%    00063    00063    00063    00063      net.thoughtforge.service.ExampleService.doSomethingWithSomething

TaskTimer 'main': running time (millis) = 4027

-------------------------------------------------------------------------------------------------
Invocations  Total Time(%)  Total Time(ms)  Min Time  Max Time  Average Time(ms)  Task Name
-------------------------------------------------------------------------------------------------
00001    100%    04027    04027    04027    04027      net.thoughtforge.service.ExampleService.doSomethingWithSomethingFiftyTimes
00050    001%    00050    00001    00001    00001      net.thoughtforge.service.ExampleService.getSomething
00050    098%    03966    00079    00095    00079      net.thoughtforge.service.ExampleService.doSomethingWithSomething

This article should act as a starting point for exploring Spring AOP and AspectJ further.  You can download the profiling aspect code and play around with Proxy based AOP and LTW, specifying the pointcut expression in the aop.xml file or within code etc.


Note: There is a rating embedded within this post, please visit this post to rate it.

jBPM is an open source BPM framework from JBoss that has matured into a real alternative to the many other BPM offerings.  The ‘jBPM Developer Guide’ introduces to its readers the main artifacts of BPM and what is involved in implementing typical jBPM solution.

The book begins by providing a background to BPM and how it can be leveraged to deliver benefit to the business.  This includes an introduction to processes, tasks and process management (Business Process Management or BAM).  As any good book should, terminologies that are associated with BPM are introduced and defined.  Thankfully, the definitions are void of the usual marketing hype.

With the help of an example, graph orientated programming (GOP) is then introduced and its relevance to jBPM discussed.  Specifically the Node, Transition and Process Definition concepts are covered before the author works through sample implementations of each.  Wait states (asynchronous system interactions and human tasks) and automatic nodes are compared before process execution is demonstrated through a sample process execution engine implementation.

The book goes on to give some background to the jBPM project and covers the setup of tools to be used throughout the remainder of the book (Maven, MySql, Eclipse etc.). It outlines how to install jBPM from a distribution and from source. I used the installer to install the version used for the examples (3.2.6.SP1).

Two example process projects are then created using the eclipse designer plugin and then the maven plugin to contrast both approaches.  Use of the ‘Graphical Process Editor’ is also demonstrated.

The jPDL language is then explored in greater depth describing in detail the XML\Class definitions of the process, the various node types (Node, Start State, End State, State, Decision), transitions and the execution token.  As an example (recruitment) process is automated with the jBPM framework.  This is achieved iteratively adding more detail in each stage.

Process instance persistence is discussed in depth.  This includes details on how and when process definition amd process instance persistence occurs.  A brief review is given of the jBPM API to interact with the database and the jBPM\Hibernate persistence configuration.

Human Task’s are explained including details on input data, task action and output data.  The distinction between a TaskNode and Task is also made.  A brief introduction to the jBPM Identity module is provided during a discussion about task assignment before demonstrating an example process.

The transactional behaviour of jBPM is then discussed along with a more detailed discussion on variable mappings and task assignment.  Process variables and the type’s of information stored in process variables are explained and the specific API for variable manipulation is covered in brief, along with the variable persistence and hierarchy. These concepts are demonstrated with a concrete example.

More advanced node types are covered in this chapter including Fork and Join nodes, Super state nodes, Process state nodes and the Email node. Variable mapping strategies as discussed in depth and related to the Process State node.

Further examples of using Super state nodes and Process state nodes are covered in addition to asynchronous execution and the JobExecutor.  The examples focused on the asynchronous execution are thorough and provide a good understanding of this process.

The book finished by discussing the use of jBPM within a JEE environment.  In particular, JTA, Data Source’s, the CommandServiceBean, the JobExecutor and JMS and finally Timers and reminders.

My overall impression of the book was that it relayed the key information required to get up and running with jBPM.  The author was clearly knowledgeable in the subject and provided useful examples to complement the concept’s being discussed.  I liked the fact that the author gives details on installing the developer tools as it allows the reader to follow along with the examples.

The only negative comment I can make was that I found the poor construction of sentences and awkward use of English a little distracting.  It reads as a book that was translated into English from another language.

One such code example that I often turn to is a logging aspect implemented using Spring AOP and AspectJ.  This logging aspect traces method entry and exit which proves very useful if you need to perform root cause analysis in pre-production environments.

In what follows, I’m going to share this code example.  I have also made the logging aspect source code available for download.

I have assumed you have a reasonable grasp of Aspect Orientated Programming concepts and terminologies.

The Logger

There are a few options to choose from when considering a logging framework and these have evolved over the years so it is probably best to abstract the logging framework from the aspect.  For this purpose, I have implemented a simple logging interface and log level enum.

package net.thoughtforge.logger;

public interface Logger {

    boolean isLogLevel(LogLevel logLevel, Class<?> clazz);

    void log(LogLevel logLevel, Class<?> clazz, Throwable throwable,
        String pattern, Object... arguments);
}

package net.thoughtforge.logger;

public enum LogLevel {
  DEBUG,
  ERROR,
  FATAL,
  INFO,
  TRACE,
  WARN
}

In the majority of cases, I end up using the Commons Logging framework and so have included this implementation of the Logger in the source download.

You may decide that this level of abstraction is overkill and that you are willing to commit to using a specific logging framework.  When making this decision, keep in mind that you will be specifying the log level throughout your code base.

The Logging Aspect

I am going to use the @Aspect approach to implement the logging aspect which is to say I will use annotations to specify the advice.  I want the logging aspect to log the method name, argument values, return value and any exception thrown so I will use the @Before, @AfterThrowing and @AfterReturning annotations.

  @Before(value = "@annotation(trace)", argNames = "joinPoint, trace")
  public void before(JoinPoint joinPoint, Loggable loggable) {

    Class<? extends Object> clazz = joinPoint.getTarget().getClass();
    String name = joinPoint.getSignature().getName();
    
    if (ArrayUtils.isEmpty(joinPoint.getArgs())) {
      logger.log(loggable.value(), clazz, null, BEFORE_STRING, name,
        constructArgumentsString(clazz, joinPoint.getArgs()));
    } else {
      logger.log(loggable.value(), clazz, null, BEFORE_WITH_PARAMS_STRING, name,
          constructArgumentsString(clazz, joinPoint.getArgs()));      
    }
  }

The ‘Before’ advice simply logs (at the appropriate log level) the method name and the toString value of all arguments (if any).  ‘Before’ advice executes when a join point is reached.

  @AfterThrowing(value = "@annotation(net.thoughtforge.aspect.Loggable)",
      throwing = "throwable", argNames = "joinPoint, throwable")
  public void afterThrowing(JoinPoint joinPoint, Throwable throwable) {

    Class<? extends Object> clazz = joinPoint.getTarget().getClass();
    String name = joinPoint.getSignature().getName();
    logger.log(LogLevel.ERROR, clazz, throwable, AFTER_THROWING, name,
        throwable.getMessage(), constructArgumentsString(clazz,
            joinPoint.getArgs()));
  }

The ‘AfterThrowing’ advice logs the method name, exception message and the toString value of all arguments (if any).  ‘AfterThrowing’ advice executes after a method exits by throwing an exception.

  @AfterReturning(value = "@annotation(trace)", returning = "returnValue",
      argNames = "joinPoint, trace, returnValue")
  public void afterReturning(JoinPoint joinPoint, Loggable loggable,
      Object returnValue) {

    Class<? extends Object> clazz = joinPoint.getTarget().getClass();
    String name = joinPoint.getSignature().getName();

    if (joinPoint.getSignature() instanceof MethodSignature) {
      MethodSignature signature = (MethodSignature) joinPoint
          .getSignature();
      Class<?> returnType = signature.getReturnType();
      if (returnType.getName().compareTo("void") == 0) {
        logger.log(loggable.value(), clazz, null, AFTER_RETURNING_VOID,
            name, constructArgumentsString(clazz, returnValue));

        return;
      }
    }

    logger.log(loggable.value(), clazz, null, AFTER_RETURNING, name,
        constructArgumentsString(clazz, returnValue));
  }

The ‘AfterReturning’ advice logs the method name and the toString value of the returned value (if any).  ‘AfterReturning’ advice executes after a method exits normally.

You will notice that I log the toString value to identify objects.  I routinely use the Apache Commons ToStringBuilder to create the toString value.   I find this particularly useful when working with persistent entities as it allows me to clearly identify the entity.

Another possible implementation that avoids using the toString method is to use the Apache Commons ReflectionToStringBuilder within the logging aspect to create a string representation of the object being logged.

If you are writing your own toString implementations (the Commons implementation is perfectly adequate) and are implementing an object with complex properties be aware of recursive invocations that may result in a stack overflow exception.

Specifying the Pointcut

A pointcut expression is an expression that specifies where in the code the advice will be applied.  With AspectJ, you can create a pointcut by specifying package, class and method attributes among other things.  I find the easiest way to specify a pointcut for the logging aspect is by matching methods that have a specific annotation.

package net.thoughtforge.aspect;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import net.thoughtforge.logger.LogLevel;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Loggable {

    LogLevel value();
}

As you can see, the Loggable annotation has one property that specifies the log level at which the log statement should be output.  Using the annotation means that developers never need to alter the pointcut expression to add or remove methods to the pointcut.  A developer only has to add the annotation to a method to have the logging aspect applied.

package net.thoughtforge.bean;

import java.util.Date;

import net.thoughtforge.aspect.Loggable;
import net.thoughtforge.logger.LogLevel;

import org.apache.commons.lang.builder.ToStringBuilder;
import org.springframework.stereotype.Component;

@Component(value = "simpleBean")
public class SimpleBean {

  private Date dateProperty;

  private Integer integerProperty;

  private String stringProperty;

  @Loggable(value = LogLevel.TRACE)
  public Date getDateProperty() {
    return dateProperty;
  }

  @Loggable(value = LogLevel.TRACE)
  public void setDateProperty(final Date dateProperty) {
    this.dateProperty = dateProperty;
  }

  @Loggable(value = LogLevel.TRACE)
  public Integer getIntegerProperty() {
    return integerProperty;
  }

  @Loggable(value = LogLevel.TRACE)
  public void setIntegerProperty(final Integer integerProperty) {
    this.integerProperty = integerProperty;
  }

  @Loggable(value = LogLevel.TRACE)
  public String getStringProperty() {
    return stringProperty;
  }

  @Loggable(value = LogLevel.TRACE)
  public void setStringProperty(final String stringProperty) {
    this.stringProperty = stringProperty;
  }

  @Override
  public String toString() {
    return new ToStringBuilder(this).append("dateProperty", dateProperty)
        .append("integerProperty", integerProperty).append(
            "stringProperty", stringProperty).toString();
  }
}

The SimpleBean and SimpleBeanSubclass are for demonstration purposes.  You can see that each method is annotated with the @Loggable annotation and the log level is set to TRACE.  You can obviously use different log levels for different methods as required.

package net.thoughtforge.bean;

import java.math.BigDecimal;

import net.thoughtforge.aspect.Loggable;
import net.thoughtforge.logger.LogLevel;

import org.apache.commons.lang.builder.ToStringBuilder;
import org.springframework.stereotype.Component;

@Component(value = "simpleBeanSubclass")
public class SimpleBeanSubclass extends SimpleBean {

  private BigDecimal decimalProperty;

  @Loggable(value = LogLevel.TRACE)
  public BigDecimal getDecimalProperty() {
    return decimalProperty;
  }

  @Loggable(value = LogLevel.TRACE)
  public void setDecimalProperty(final BigDecimal decimalProperty) {
    this.decimalProperty = decimalProperty;
  }

  @Override
  public String toString() {
    return new ToStringBuilder(this).append("decimalProperty",
        decimalProperty).appendSuper(super.toString()).toString();
  }
}

Also note the use of the ToStringBuilder to create the toString value.  You may choose to use the ReflectionToStringBuilder or some other mechanism.

Testing the Logging Aspect

One way to test the logging aspect is to simply have a test invoke instrumented methods and observe the log statements produced.  This is a useful exercise but requires manual intervention to determine if the test was successful.

In order to create an automated test for the logging aspect, I needed to create a mock logger that simulates the actions of a logger and allows me to interrogate the log statements produced.

package net.thoughtforge.mock.logger;

import java.text.MessageFormat;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import net.thoughtforge.logger.LogLevel;
import net.thoughtforge.logger.Logger;

import org.springframework.stereotype.Component;

@Component
public class MockLogger implements Logger {

  private Map<Class<?>, LogLevel> logLevelMap =
    new HashMap<Class<?>, LogLevel>();
  
  private Map<Class<?>, List<LogMessage>> messages = new HashMap<Class<?>, List<LogMessage>>();
  
  public boolean isLogLevel(LogLevel logLevel,  Class<?> clazz) {
    boolean result = false;

    switch (logLevel) {
      case DEBUG:
        result = isLogLevelEnabled(clazz, LogLevel.DEBUG);
  
      case ERROR:
        result = isLogLevelEnabled(clazz, LogLevel.ERROR);
  
      case FATAL:
        result = isLogLevelEnabled(clazz, LogLevel.FATAL);
  
      case INFO:
        result = isLogLevelEnabled(clazz, LogLevel.INFO);
  
      case TRACE:
        result = isLogLevelEnabled(clazz, LogLevel.TRACE);
  
      case WARN:
        result = isLogLevelEnabled(clazz, LogLevel.WARN);
  
      default:
        result = false;
    }
    
    return result;
  }

  public void log(LogLevel logLevel,  Class<?> clazz,
       Throwable throwable,  String pattern,
       Object... arguments) {

    switch (logLevel) {
      case DEBUG:
        debug(clazz, throwable, pattern, arguments);
        break;
  
      case ERROR:
        error(clazz, throwable, pattern, arguments);
        break;
  
      case FATAL:
        fatal(clazz, throwable, pattern, arguments);
        break;
  
      case INFO:
        info(clazz, throwable, pattern, arguments);
        break;
  
      case TRACE:
        trace(clazz, throwable, pattern, arguments);
        break;
  
      case WARN:
        warn(clazz, throwable, pattern, arguments);
        break;
    }
  }

  private void debug(Class<?> clazz,  Throwable throwable,
       String pattern,  Object... arguments) {

    if (throwable != null) {
      getMessages(clazz).add(new LogMessage(LogLevel.DEBUG, format(pattern, arguments), throwable));
    } else {
      getMessages(clazz).add(new LogMessage(LogLevel.DEBUG, format(pattern, arguments)));
    }
  }

  private void error(Class<?> clazz,  Throwable throwable,
       String pattern,  Object... arguments) {

    if (throwable != null) {
      getMessages(clazz).add(new LogMessage(LogLevel.ERROR, format(pattern, arguments), throwable));
    } else {
      getMessages(clazz).add(new LogMessage(LogLevel.ERROR, format(pattern, arguments)));
    }
  }

  private void fatal(Class<?> clazz,  Throwable throwable,
       String pattern,  Object... arguments) {

    if (throwable != null) {
      getMessages(clazz).add(new LogMessage(LogLevel.FATAL, format(pattern, arguments), throwable));
    } else {
      getMessages(clazz).add(new LogMessage(LogLevel.FATAL, format(pattern, arguments)));
    }
  }

  private void info(Class<?> clazz,  Throwable throwable,
       String pattern,  Object... arguments) {

    if (throwable != null) {
      getMessages(clazz).add(new LogMessage(LogLevel.INFO, format(pattern, arguments), throwable));
    } else {
      getMessages(clazz).add(new LogMessage(LogLevel.INFO, format(pattern, arguments)));
    }
  }

  private void trace( Class<?> clazz,  Throwable throwable,
       String pattern,  Object... arguments) {

    if (throwable != null) {
      getMessages(clazz).add(new LogMessage(LogLevel.TRACE, format(pattern, arguments), throwable));
    } else {
      getMessages(clazz).add(new LogMessage(LogLevel.TRACE, format(pattern, arguments)));
    }
  }

  private void warn( Class<?> clazz,  Throwable throwable,
       String pattern,  Object... arguments) {

    if (throwable != null) {
      getMessages(clazz).add(new LogMessage(LogLevel.WARN, format(pattern, arguments), throwable));
    } else {
      getMessages(clazz).add(new LogMessage(LogLevel.WARN, format(pattern, arguments)));
    }
  }

  private String format( String pattern,  Object... arguments) {

    return MessageFormat.format(pattern, arguments);
  }

  public void resetLoggers() {
    messages = new HashMap<Class<?>, List<LogMessage>>();
  }
  
  public List<LogMessage> getMessages(Class<?> clazz) {
    if (messages.get(clazz) == null) {
      messages.put(clazz, new ArrayList<LogMessage>());
    }
    
    return messages.get(clazz);
  }

  private boolean isLogLevelEnabled(Class<?> clazz, LogLevel logLevel) {
    return logLevelMap.get(clazz) != null && logLevelMap.get(clazz).equals(logLevel);
  }
  
  public void setLogLevel(Class<?> clazz, LogLevel logLevel) {
    logLevelMap.put(clazz, logLevel);
  }
  
  public class LogMessage {
    private LogLevel logLevel;
    
    private String message;
    
    private Throwable throwable;

    public LogMessage(LogLevel logLevel, String message, Throwable throwable) {
      this(logLevel, message);
      this.throwable = throwable;
    }
    
    public LogMessage(LogLevel logLevel, String message) {
      this.logLevel = logLevel;
      this.message = message;
    }
    
    public LogLevel getLogLevel() {
      return logLevel;
    }
    
    public String getMessage() {
      return message;
    }
    
    public Throwable getThrowable() {
      return throwable;
    }
  }
}

The logging aspect test utilises the MockLogger and makes assertions about the log statements produced.

package net.thoughtforge.aspect;

import java.math.BigDecimal;

import junit.framework.Assert;
import net.thoughtforge.bean.SimpleBean;
import net.thoughtforge.bean.SimpleBeanSubclass;
import net.thoughtforge.logger.LogLevel;
import net.thoughtforge.mock.logger.MockLogger;
import net.thoughtforge.mock.logger.MockLogger.LogMessage;

import org.apache.commons.lang.time.DateUtils;
import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = {
    "/applicationContext/applicationContext-aspect.xml",
    "/applicationContext/applicationContext-logger.xml",
    "/applicationContext/applicationContext.xml" })
public class LoggingAspectTest {

  @Autowired
  private MockLogger logger;
  
  @Autowired
  @Qualifier(value = "simpleBean")
  public SimpleBean simpleBean;

  @Autowired
  public SimpleBeanSubclass simpleBeanSubclass;

  @Before
  public void before() {
    logger.setLogLevel(SimpleBean.class, LogLevel.TRACE);
    logger.setLogLevel(SimpleBeanSubclass.class, LogLevel.TRACE);
    logger.resetLoggers();
  }
  
  @Test
  public void testSimpleBean_SetDateProperty() throws Exception {
    simpleBean.setDateProperty(
        DateUtils.parseDate("01/01/2010", new String[] {"dd/MM/yyyy"}));
    
    Assert.assertEquals(2, logger.getMessages(SimpleBean.class).size());
    assertEquals(logger.getMessages(SimpleBean.class).get(0),
        LogLevel.TRACE,
        "[ entering < setDateProperty > with params Fri Jan 01 00:00:00 GMT 2010 ]");
    assertEquals(logger.getMessages(SimpleBean.class).get(1),
        LogLevel.TRACE,
        "[ leaving < setDateProperty > ]");
  }
  
  @Test
  public void testSimpleBean_SetIntegerProperty() {
    simpleBean.setIntegerProperty(100);
    
    Assert.assertEquals(2, logger.getMessages(SimpleBean.class).size());
    assertEquals(logger.getMessages(SimpleBean.class).get(0),
        LogLevel.TRACE,
        "[ entering < setIntegerProperty > with params 100 ]");
    assertEquals(logger.getMessages(SimpleBean.class).get(1),
        LogLevel.TRACE,
        "[ leaving < setIntegerProperty > ]");
  }
  
  @Test
  public void testSimpleBean_SetStringProperty() {
    simpleBean.setStringProperty("stringProperty");
    
    Assert.assertEquals(2, logger.getMessages(SimpleBean.class).size());
    assertEquals(logger.getMessages(SimpleBean.class).get(0),
        LogLevel.TRACE,
        "[ entering < setStringProperty > with params stringProperty ]");
    assertEquals(logger.getMessages(SimpleBean.class).get(1),
        LogLevel.TRACE,
        "[ leaving < setStringProperty > ]");
  }
  
  @Test
  public void testSimpleBean_GetDateProperty() {
    simpleBean.getDateProperty();
    
    Assert.assertEquals(2, logger.getMessages(SimpleBean.class).size());
    assertEquals(logger.getMessages(SimpleBean.class).get(0),
        LogLevel.TRACE,
        "[ entering < getDateProperty > ]");
    assertEquals(logger.getMessages(SimpleBean.class).get(1),
        LogLevel.TRACE,
        "[ leaving < getDateProperty > returning Fri Jan 01 00:00:00 GMT 2010 ]");
  }
  
  @Test
  public void testSimpleBean_GetIntegerProperty() {
    simpleBean.getIntegerProperty();
    
    Assert.assertEquals(2, logger.getMessages(SimpleBean.class).size());
    assertEquals(logger.getMessages(SimpleBean.class).get(0),
        LogLevel.TRACE,
        "[ entering < getIntegerProperty > ]");
    assertEquals(logger.getMessages(SimpleBean.class).get(1),
        LogLevel.TRACE,
        "[ leaving < getIntegerProperty > returning 100 ]");
  }
  
  @Test
  public void testSimpleBean_GetStringProperty() {
    simpleBean.getStringProperty();
    
    Assert.assertEquals(2, logger.getMessages(SimpleBean.class).size());
    assertEquals(logger.getMessages(SimpleBean.class).get(0),
        LogLevel.TRACE,
        "[ entering < getStringProperty > ]");
    assertEquals(logger.getMessages(SimpleBean.class).get(1),
        LogLevel.TRACE,
        "[ leaving < getStringProperty > returning stringProperty ]");
  }

  @Test
  public void testSimpleBeanSubclass_SetDateProperty() throws Exception {
    simpleBeanSubclass.setDateProperty(
        DateUtils.parseDate("01/01/2010", new String[] {"dd/MM/yyyy"}));
    
    Assert.assertEquals(2, logger.getMessages(SimpleBeanSubclass.class).size());
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(0),
        LogLevel.TRACE,
        "[ entering < setDateProperty > with params Fri Jan 01 00:00:00 GMT 2010 ]");
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(1),
        LogLevel.TRACE,
        "[ leaving < setDateProperty > ]");
  }
  
  @Test
  public void testSimpleBeanSubclass_SetDecimalProperty() {
    simpleBeanSubclass.setDecimalProperty(new BigDecimal("0.25"));
    
    Assert.assertEquals(2, logger.getMessages(SimpleBeanSubclass.class).size());
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(0),
        LogLevel.TRACE,
        "[ entering < setDecimalProperty > with params 0.25 ]");
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(1),
        LogLevel.TRACE,
        "[ leaving < setDecimalProperty > ]");
  }
  
  @Test
  public void testSimpleBeanSubclass_SetIntegerProperty() {
    simpleBeanSubclass.setIntegerProperty(100);
    
    Assert.assertEquals(2, logger.getMessages(SimpleBeanSubclass.class).size());
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(0),
        LogLevel.TRACE,
        "[ entering < setIntegerProperty > with params 100 ]");
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(1),
        LogLevel.TRACE,
        "[ leaving < setIntegerProperty > ]");
  }
  
  @Test
  public void testSimpleBeanSubclass_SetStringProperty() {
    simpleBeanSubclass.setStringProperty("stringProperty");
    
    Assert.assertEquals(2, logger.getMessages(SimpleBeanSubclass.class).size());
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(0),
        LogLevel.TRACE,
        "[ entering < setStringProperty > with params stringProperty ]");
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(1),
        LogLevel.TRACE,
        "[ leaving < setStringProperty > ]");
  }
  
  @Test
  public void testSimpleBeanSubclass_GetDateProperty() {
    simpleBeanSubclass.getDateProperty();
    
    Assert.assertEquals(2, logger.getMessages(SimpleBeanSubclass.class).size());
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(0),
        LogLevel.TRACE,
        "[ entering < getDateProperty > ]");
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(1),
        LogLevel.TRACE,
        "[ leaving < getDateProperty > returning Fri Jan 01 00:00:00 GMT 2010 ]");
  }
  
  @Test
  public void testSimpleBeanSubclass_GetDecimalProperty() {
    simpleBeanSubclass.getDecimalProperty();
    
    Assert.assertEquals(2, logger.getMessages(SimpleBeanSubclass.class).size());
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(0),
        LogLevel.TRACE,
        "[ entering < getDecimalProperty > ]");
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(1),
        LogLevel.TRACE,
        "[ leaving < getDecimalProperty > returning 0.25 ]");
  }
  
  @Test
  public void testSimpleBeanSubclass_GetIntegerProperty() {
    simpleBeanSubclass.getIntegerProperty();
    
    Assert.assertEquals(2, logger.getMessages(SimpleBeanSubclass.class).size());
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(0),
        LogLevel.TRACE,
        "[ entering < getIntegerProperty > ]");
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(1),
        LogLevel.TRACE,
        "[ leaving < getIntegerProperty > returning 100 ]");
  }
  
  @Test
  public void testSimpleBeanSubclass_GetStringProperty() {
    simpleBeanSubclass.getStringProperty();
    
    Assert.assertEquals(2, logger.getMessages(SimpleBeanSubclass.class).size());
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(0),
        LogLevel.TRACE,
        "[ entering < getStringProperty > ]");
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(1),
        LogLevel.TRACE,
        "[ leaving < getStringProperty > returning stringProperty ]");
  }
  
  private void assertEquals(LogMessage logMessage, LogLevel logLevel, String message) {
    Assert.assertEquals(logLevel, logMessage.getLogLevel());
    
    Assert.assertEquals(message, logMessage.getMessage());    
  }
}

The test is not exhaustive but suffices to test the general operation of the logging aspect.

Final Word

Hopefully you found my example useful but I will finish by saying that there are many choices that I made in deciding on this approach.

A strong argument could be made for the use of XML configuration as opposed to the @Aspect approach which allows you greater control over the execution of the advice without modifying code.  This would be particularly relevant in an environment where performance was a major focus.  I personally have found that the control provided by logging frameworks to enable and disable particular loggers is sufficient in most environments.

You can download the source code in the form of a Maven project and follow along.

Hibernate Validator Dependencies

First step is to add the Hibernate Validator dependency to the project pom. I have used Hibernate Validator 4.0.0.GA because it is a JSR 303 compliant implementation.

<dependency>
  <groupId>org.hibernate</groupId>
  <artifactId>hibernate-validator</artifactId>
  <version>4.0.0.GA</version>
  <scope>compile</scope>
</dependency>

Annotating the Model Class

JSR 303 allows for the specification of validation constraints via Annotations and\or XML. The Hibernate Validator documentation has recently been updated to include details on specifying the validation.xml if you prefer to use XML.

For this example I am going to use Annotations to specify a ‘Size’ constraint on the name and description properties of the Organisation class. These are basic constraints but they will suffice for demonstration purposes.

package net.thoughtforge.model;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

import javax.validation.constraints.Size;

import org.springframework.context.annotation.Scope;
import org.springframework.stereotype.Component;

@Component
@Scope("prototype")
public class Organisation implements Serializable {

  private static final long serialVersionUID = -2023156931701914562L;

  private List<Organisation> children;
  
  @Size(min=3, max=200, message="Description must be between 3 and 200 characters in length.")
  private String description;
  
  @Size(min=3, max=50, message="Name must be between 3 and 50 characters in length.")
  private String name;

  private Organisation parent;
  
  public void addChild(Organisation child) {
        if (child.getParent() == null || !child.getParent().equals(this)) {
            child.setParent(this);
        }
        
        if (children == null) {
            children = new ArrayList<Organisation>();
        }
        
        if (!children.contains(child)) {
          children.add(child);
        }
  }
  
  public void removeChild(Organisation child) {
        if (child.getParent() != null && child.getParent().equals(this)) {
            child.setParent(null);
        }
        
        if (children != null) {
            children.remove(child);
        }
  }

  public List<Organisation> getChildren() {
    if (children == null) {
      children = new ArrayList<Organisation>();
    }
    
    return Collections.unmodifiableList(children);
  }
  
  public String getDescription() {
    return description;
  }

  public void setDescription(String description) {
    this.description = description;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public Organisation getParent() {
    return parent;
  }

  public void setParent(Organisation parent) {
    this.parent = parent;
  }
}

Applying the Constraints

Of course, as annotations do nothing in and of themselves, I need to invoke the validator to apply the constraints. RichFaces provides 3 components that invoke either the Hibernate or JSR 303 bean validator during the JSF ‘Process Validations’ phase.

I wanted to validate the Organisation name and description properties. These are set within the ‘addChildModalPanel’ and updated within the ‘editChildModalPanel’. The validations are applied to each in exactly the same way.

To apply validations to the name and description ‘inputText’ fields I added a child field. Adding this child component results in the validator being invoked during the ‘Process Validations’ phase.

<h:inputText value="#{addChildOrganisation.name}">
  <rich:beanValidator/>
</h:inputText>

If the validation fails, messages are added to the FacesContext and will be displayed using the component.

<rich:messages>
  <f:facet name="errorMarker">
    <h:panelGroup>
      <h:graphicImage value="/image/error.gif"/>
      <h:outputText value="  "/>
    </h:panelGroup>
  </f:facet>
</rich:messages>

Displaying Validation Messages within the Modal Dialog

Finally, I needed to keep the Modal Dialog from closing when validation failures occured. This is achieved by modifying the a4j:commandButton as shown below. It is worth highlighting that each has its own and this is very important (as highlighted in the JBoss RichFaces documentation).

<a4j:commandButton action="addChildModalPanelConfirm"
    value="Ok"
    oncomplete="if (#{!facesContext.messages.hasNext()}) {Richfaces.hideModalPanel('addChildModalPanel')};"
    reRender="dynamicTreePanel"
    styleClass="commandButton"/>

What I ended up with was a really intuitive and responsive UI with appropriate validations. It was an interesting exercise especially due to the intricacies of the component.

Many popular ‘Object-Relational Mapping’ (ORM) frameworks exist that address the object-relational impedance mismatch and no doubt helped to inspire the evolution of ‘Object-XML Mapping’ (OXM) frameworks to address the object-xml impedance mismatch.

For the Java community, there are a number of OXM frameworks from which to choose (Castor, XStream, JiBX, JAXB) with each having particular strengths and weaknesses. The standard OXM framework for Java is JAXB.

In the following I work through a simple example that demonstrates object to XML marshalling (and demarshalling) using Spring, Spring WS and JAXB (and later JAXB Introductions!)

I have provided Maven projects for download so you can follow along:

Spring OXM and JAXB Source Download
Spring OXM, JAXB and JAXB Introductions Download

The Model

The model object that I have used for this example is a simple object representing a ‘Person’. The class contains only simple attributes.

package net.thoughtforge.model;

import java.io.Serializable;
import java.math.BigDecimal;
import java.util.Calendar;

import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;
import javax.xml.bind.annotation.XmlType;

@XmlRootElement(
    name="Person",
    namespace="http://thoughtforge.net/model")
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType
public class Person implements Serializable {

  private static final long serialVersionUID = 8465162879793776395L;

  @XmlElement(namespace="http://thoughtforge.net/model")
  private Calendar dateOfBirth;
  
  @XmlElement(namespace="http://thoughtforge.net/model")
  private String firstName;
  
  @XmlElement(namespace="http://thoughtforge.net/model")
  private BigDecimal height;
  
  @XmlElement(namespace="http://thoughtforge.net/model")
  private String lastName;
  
  @XmlElement(namespace="http://thoughtforge.net/model")
  private BigDecimal weight;

  public Calendar getDateOfBirth() {
    return dateOfBirth;
  }

  public void setDateOfBirth(Calendar dateOfBirth) {
    this.dateOfBirth = dateOfBirth;
  }

  public String getFirstName() {
    return firstName;
  }

  public void setFirstName(String firstName) {
    this.firstName = firstName;
  }

  public BigDecimal getHeight() {
    return height;
  }

  public void setHeight(BigDecimal height) {
    this.height = height;
  }

  public String getLastName() {
    return lastName;
  }

  public void setLastName(String lastName) {
    this.lastName = lastName;
  }

  public BigDecimal getWeight() {
    return weight;
  }

  public void setWeight(BigDecimal weight) {
    this.weight = weight;
  }
}

As you can see from the listing, the class is annotated with JAXB annotations that are fairly self explanatory. I will leave it to you to look up the precise definition and consequence of these annotations (which can be found on the JAXB Reference Implementation website).

The XML Schema (XSD)

JAXB does not require an XML schema (a default schema can be generated), but for this example (and always on commercial projects) I have explicitly specified a schema in order to include type restrictions. It is important to remember that the XSD forms the contract between XML producers and consumers (marshaller and unmarshaller) and should be as detailed as possible.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://thoughtforge.net/model"
  xmlns:tns="http://thoughtforge.net/model"
  attributeFormDefault="unqualified"
  elementFormDefault="qualified"
  version="1.0">

  <xsd:element name="Person" type="tns:Person"/>
  
  <xsd:complexType name="Person">
    <xsd:sequence>
      <xsd:element name="dateOfBirth" type="xsd:dateTime"/>
      <xsd:element name="firstName">
        <xsd:simpleType>
          <xsd:restriction base="xsd:string">
            <xsd:maxLength value="50"/>
          </xsd:restriction>
        </xsd:simpleType>
      </xsd:element>
      <xsd:element name="height">
        <xsd:simpleType>
          <xsd:restriction base="xsd:decimal">
            <xsd:fractionDigits value="2"/>
          </xsd:restriction>
        </xsd:simpleType>
      </xsd:element>
      <xsd:element name="lastName">
        <xsd:simpleType>
          <xsd:restriction base="xsd:string">
            <xsd:maxLength value="50"/>
          </xsd:restriction>
        </xsd:simpleType>
      </xsd:element>
      <xsd:element name="weight">
        <xsd:simpleType>
          <xsd:restriction base="xsd:decimal">
            <xsd:fractionDigits value="2"/>
          </xsd:restriction>
        </xsd:simpleType>
      </xsd:element>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>

The Marshaller Abstraction

Rather than use the Spring Marshaller/Unmarshaller interface directly, I often use an abstraction for the Marshaller. The abstraction I used here is very simple and of course would not be practical for use with large XML files as it does not support streaming etc.

package net.thoughtforge.marshaller;

public interface Marshaller {

  String marshal(Object object);

  Object unmarshal(String string);
}

The implementation of the marshaller delegates to a Spring JAXB marshaller.

package net.thoughtforge.marshaller;

import java.io.StringWriter;

import javax.xml.transform.stream.StreamResult;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Component;
import org.springframework.xml.transform.StringSource;

@Component(value="marshaller")
public class Jaxb2Marshaller implements Marshaller {

  @Autowired
  @Qualifier(value="jaxb2Marshaller")
  private org.springframework.oxm.jaxb.Jaxb2Marshaller marshaller;
  
  public String marshal(Object object) {
    final StringWriter out = new StringWriter();
    marshaller.marshal(object, new StreamResult(out));
    return out.toString();
  }

  public Object unmarshal(String string) {
    return marshaller.unmarshal(new StringSource(string));
  }
}

The Configuration

Using Spring to define a JAXB marshaller is relatively straight forward as the listing shows. I have specified the classes to be bound and the XML schema. If the XML schema is specified, the marshaller will instruct the XML parser to validate XML against the schema.

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:context="http://www.springframework.org/schema/context"
  xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
    http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">

  <context:component-scan base-package="net.thoughtforge.marshaller"/>
  
  <bean id="jaxb2Marshaller" class="org.springframework.oxm.jaxb.Jaxb2Marshaller">
    <property name="classesToBeBound">
      <list>
        <value>net.thoughtforge.model.Person</value>
      </list>
    </property>
    <property name="schema" value="classpath:schema/person.xsd"/>
  </bean>
</beans>

The Test

The following test is not exhaustive but demonstrates the marshalling and unmarshalling of a Person object. It also demonstrates XML schema validation occurring during the marshalling and unmarshalling process.

package net.thoughtforge.marshaller;

import java.math.BigDecimal;
import java.util.Calendar;

import net.thoughtforge.model.Person;

import org.apache.commons.lang.text.StrBuilder;
import org.junit.Assert;
import org.junit.BeforeClass;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.oxm.MarshallingFailureException;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = {
    "classpath:applicationContext/applicationContext-*.xml"})
public class Jaxb2MarshallerTest {

  private static final String MARSHALLED_PERSON =
    "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><Person xmlns=\"http://thoughtforge.net/model\"><dateOfBirth>1965-01-01T00:00:00Z</dateOfBirth><firstName>Joe</firstName><height>1.85</height><lastName>Bloggs</lastName><weight>12.2</weight></Person>";
  
  private static Calendar dateOfBirth;
  
  private static String firstName;
  
  private static BigDecimal height;
  
  private static String lastName;
  
  private static BigDecimal weight;
  
  @Autowired
  @Qualifier(value="marshaller")
  private Jaxb2Marshaller marshaller;

  @BeforeClass
  public static void beforeClass() {
    dateOfBirth = Calendar.getInstance();
    dateOfBirth.clear();
    dateOfBirth.set(Calendar.DATE, 1);
    dateOfBirth.set(Calendar.MONTH, Calendar.JANUARY);
    dateOfBirth.set(Calendar.YEAR, 1965);
    
    firstName = "Joe";
    height = new BigDecimal("1.85");
    lastName = "Bloggs";
    weight = new BigDecimal("12.2");
  }
  
  @Test
  public void marshallPerson() {
    Person person = new Person();
    person.setDateOfBirth(dateOfBirth);
    person.setFirstName(firstName);
    person.setHeight(height);
    person.setLastName(lastName);
    person.setWeight(weight);
    
    String xml = marshaller.marshal(person);
    
    Assert.assertNotNull(xml);
    Assert.assertEquals(MARSHALLED_PERSON, xml);
  }

  @Test
  public void marshallPersonInvalidFirstName() {
    Person person = new Person();
    person.setDateOfBirth(dateOfBirth);
    person.setFirstName(new StrBuilder(firstName).appendPadding(50, '0').toString());
    person.setHeight(height);
    person.setLastName(lastName);
    person.setWeight(weight);
    
    try {
      marshaller.marshal(person);
      Assert.fail("First name length restriction not applied.");
    } catch (MarshallingFailureException marshallingFailureException) {
      Throwable rootCause = marshallingFailureException.getRootCause();
      Assert.assertFalse(rootCause.getMessage().indexOf("is not facet-valid with respect to maxLength '50'") == -1);
    }
  }
  
  @Test
  public void marshallPersonInvalidHeight() {
    Person person = new Person();
    person.setDateOfBirth(dateOfBirth);
    person.setFirstName(firstName);
    person.setHeight(height.add(new BigDecimal("0.1111")));
    person.setLastName(lastName);
    person.setWeight(weight);
    
    try {
      marshaller.marshal(person);
      Assert.fail("Height precision restriction not applied.");
    } catch (MarshallingFailureException marshallingFailureException) {
      Throwable rootCause = marshallingFailureException.getRootCause();
      Assert.assertFalse(rootCause.getMessage().indexOf("the number of fraction digits has been limited to 2") == -1);
    }
  }
  
  @Test
  public void marshallPersonInvalidLastName() {
    Person person = new Person();
    person.setDateOfBirth(dateOfBirth);
    person.setFirstName(firstName);
    person.setHeight(height);
    person.setLastName(new StrBuilder(lastName).appendPadding(50, '0').toString());
    person.setWeight(weight);
    
    try {
      marshaller.marshal(person);
      Assert.fail("First name length restriction not applied.");
    } catch (MarshallingFailureException marshallingFailureException) {
      Throwable rootCause = marshallingFailureException.getRootCause();
      Assert.assertFalse(rootCause.getMessage().indexOf("is not facet-valid with respect to maxLength '50'") == -1);
    }
  }
  
  @Test
  public void marshallPersonInvalidWeight() {
    Person person = new Person();
    person.setDateOfBirth(dateOfBirth);
    person.setFirstName(firstName);
    person.setHeight(height);
    person.setLastName(lastName);
    person.setWeight(weight.add(new BigDecimal("0.1111")));
    
    try {
      marshaller.marshal(person);
      Assert.fail("Weight precision restriction not applied.");
    } catch (MarshallingFailureException marshallingFailureException) {
      Throwable rootCause = marshallingFailureException.getRootCause();
      Assert.assertFalse(rootCause.getMessage().indexOf("the number of fraction digits has been limited to 2") == -1);
    }
  }
  @Test
  public void unmarshallPerson() {
    Person person = (Person) marshaller.unmarshal(MARSHALLED_PERSON);
    
    Assert.assertNotNull(person);
    Assert.assertTrue(dateOfBirth.compareTo(person.getDateOfBirth()) == 0);
    Assert.assertEquals(firstName, person.getFirstName());
    Assert.assertEquals(height, person.getHeight());
    Assert.assertEquals(lastName, person.getLastName());
    Assert.assertEquals(weight, person.getWeight());
  }
}

Removing JAXB Annotations

If you are using the reference implementation of JAXB you are required to use annotations to map objects to XML. As I mentioned in a previous post, I’m not a fan of using annotations for the purpose of mapping objects to some other format (relational database or XML or A.N. Other). I find it creates code clutter especially in instances were entity model classes are mapped to both a relational database and XML (using JAXB). In modular projects, it also creates unnecessary dependencies on the model module.

Luckily, some bright spark came along and created JAXB Introductions which allows you to define the mapping of objects to XML in an XML file. I’m not going to regurgitate the information on the JAXB Introductions website but I will outline the modifications I had to make to allow me to use JAXB Introductions with the example above.

First, I added the maven dependency to the project.

    <dependency>
        <groupId>jboss.jaxbintros</groupId>
        <artifactId>jboss-jaxb-intros</artifactId>
        <version>1.0.1.GA</version>
    </dependency>

Second, I created a JAXB Introductions mapping file.

<?xml version = "1.0" encoding = "UTF-8"?>

<jaxb-intros xmlns="http://www.jboss.org/xsd/jaxb/intros">
    <Class name="net.thoughtforge.model.Person">
        <XmlType/>
        <XmlRootElement name="Person" namespace="http://thoughtforge.net/model"/>
        <XmlAccessorType value="FIELD"/>

        <Field name="dateOfBirth">
            <XmlElement name="dateOfBirth" namespace="http://thoughtforge.net/model"/>
        </Field>
        <Field name="firstName">
            <XmlElement name="firstName" namespace="http://thoughtforge.net/model"/>
        </Field>
        <Field name="height">
            <XmlElement name="height" namespace="http://thoughtforge.net/model"/>
        </Field>
        <Field name="lastName">
            <XmlElement name="lastName" namespace="http://thoughtforge.net/model"/>
        </Field>
        <Field name="weight">
            <XmlElement name="weight" namespace="http://thoughtforge.net/model"/>
        </Field>
    </Class>
</jaxb-intros>

Thirdly, I modified the Spring configuration to inject the JAXB Introductions annotation reader into the JAXB marshaller.

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:context="http://www.springframework.org/schema/context"
  xmlns:util="http://www.springframework.org/schema/util"
  xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
    http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-2.0.xsd
    http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">

  <context:component-scan base-package="net.thoughtforge.marshaller"/>
  
  <bean id="jaxb2Marshaller" class="org.springframework.oxm.jaxb.Jaxb2Marshaller">
    <property name="classesToBeBound">
      <list>
        <value>net.thoughtforge.model.Person</value>
      </list>
    </property>
    <property name="jaxbContextProperties">
            <map>
                <entry>
                    <key>
                        <util:constant static-field="com.sun.xml.bind.api.JAXBRIContext.ANNOTATION_READER"/>
                    </key>
                  
                    <bean class="org.jboss.jaxb.intros.IntroductionsAnnotationReader">
                        <constructor-arg ref="jaxbIntroductions"/>
                    </bean>
                </entry>
            </map>
    </property>
    <property name="schema" value="classpath:schema/person.xsd"/>
  </bean>

    <bean id="jaxbIntroductions" class="org.jboss.jaxb.intros.IntroductionsConfigParser"
            factory-method="parseConfig">
        <constructor-arg><value>classpath:marshaller-mapping.xml</value></constructor-arg>
    </bean>
</beans>

Finally, I removed the JAXB annotations from the model class (Person.java).

package net.thoughtforge.model;

import java.io.Serializable;
import java.math.BigDecimal;
import java.util.Calendar;

public class Person implements Serializable {

  private static final long serialVersionUID = 8465162879793776395L;

  private Calendar dateOfBirth;
  
  private String firstName;
  
  private BigDecimal height;
  
  private String lastName;
  
  private BigDecimal weight;

  public Calendar getDateOfBirth() {
    return dateOfBirth;
  }

  public void setDateOfBirth(Calendar dateOfBirth) {
    this.dateOfBirth = dateOfBirth;
  }

  public String getFirstName() {
    return firstName;
  }

  public void setFirstName(String firstName) {
    this.firstName = firstName;
  }

  public BigDecimal getHeight() {
    return height;
  }

  public void setHeight(BigDecimal height) {
    this.height = height;
  }

  public String getLastName() {
    return lastName;
  }

  public void setLastName(String lastName) {
    this.lastName = lastName;
  }

  public BigDecimal getWeight() {
    return weight;
  }

  public void setWeight(BigDecimal weight) {
    this.weight = weight;
  }
}

Hopefully, this short example will prove useful for those starting out with JAXB and OXM. For those already familiar with JAXB and OXM, perhaps it has shown you how you can use JAXB without annotations.