Let us assume that you want to keep track of user and time a set of entity types has been updated. So you would add a component mapping to all of the entity mappings where this feature is required.

This can get really tedious, so you might want to look for a more elegant solution that allows re-using this component mapping. Hibernate does not offer a mapping element that allows to include some externalized mapping fragment. But XML supports including XML documents through it’s DTD entity facility.

So you first start by moving the XML fragment that should be reusable to a file (e.g. domain/model/LastUpdate.xml)

For mapping file that requires the lastUpdate component an external ENTITY declaration must be added, the entity reference (&lastUpdate;) is a place holder that is replaced by the entity.

]>

	
		

		
		&lastUpdate;
	

A few quotes from chapter 2 which is mostly about a ubiquitous language:

The vital detail about the design is captured on the code.

About documents:

A document shouldn’ try to do what the code already does well.

If documents are written at all (see Extreme Programming):

Documents should work for a living and stay current (I have never been a friend of paper work!).