martes, diciembre 03, 2013

Are Configuration Files Documentation? ... Yes!!! TomEE + Asciidoctor Example


Normally in our projects we generate a considerable amount of documentation. Some documentation is directly a document written as is, for example Software Requirements Specifications (SRS) or Software Design Specifications (SDS), but there are other pieces of our projects that although they are not a document directly, they are consulted by developers/testers/managers, customers ... and treat it as is, for example user stories written by developers and/or QA in Cucumber or JBehave format or  javadoc. And now I ask to myself, are configuration files documentation too? Are people interested in having them in a document and treat them as documentation? And the answer is YES!!!. In this post we are going to see how to transform TomEE's configuration file into a document using an Asciidoctor extension I have developed specially for this occasion.

In TomEE, resources and containers can be configured inside a file called tomee.xml among other places. But what really makes interesting is that a subset of this file can be put inside the project, so each web application is responsible of configuring their own resources, for example DataSources, JMS Queues, ....  And having the ability of putting specific configuration of the server inside the application also opens the doors of creating more than one configuration file per application, and load one or another depending on the environment we are going to deploy the application. For example:
  • In developer environment the DataSource could point to an embedded database.
  • In QA environment the DataSource could point to a database installed on localhost.
  • In Stage environment the same DataSource points to an external IP1.
  • In Production environment the same DataSource points to an external IP2.
So as you can see, it would be interesting to have all these information as readable documentation, so everyone involved in the project could review it and for example know exactly which servers are being used in each environment as datasources, or configuration parameters like pool size of stateless manager.

And this is exactly what tomee-asciidoctor-extension does. It allows us to embed Apache TomEE configuration files into an AsciiDoc documentation.

Let's see an example of Apache TomEE configuration file:


This is a typical configuration file where for example you can see some DataSources defined, custom resource or definition of TransactionManager.

Probably your projects will have a document called for example infrastructure (or something similar) where all information related with the software that is being used in the project and  environments used will be described.

A simple example of these kind of documents can be:

Note that besides describing the software that is going to be used for solving our problem, in this case an Apache TomEE, we are using the tomee-asciidoctor-extension to add the Apache TomEE's container and resources configuration file, so when someone wants to inspect the documentation will also see exactly the configuration values that had Apache TomEE at time of generating the document. If you look carefully you only need to add next line to transform a Apache TomEE configuration file into documentation:

include::tomee:/home/alex/git/asciidoctorj-extensions/tomee-asciidoctorj-extensions/src/test/resources/resources.xml[initialLevel=2]

In this case we are including a file called resources.xml. Note that in order to extension detects an Apache TomEE configuration file, we need to use the special keyword tomee: followed by the location of the file. Also note that we are using an attribute called initialLevel. Because we are embedding one document into another one, we need a way to set at which level the document will be rendered, and this is what this attribute is designed for.

Previous document rendered with default style sheet looks like:



See that thanks of Asciidoctor and its extension system, we are able to convert configuration files to documentation.

You can see the code of this extension at: https://github.com/lordofthejars/asciidoctorj-extensions/tree/master/tomee-asciidoctorj-extensions

We keep learning,
Alex.
Siente y baila y goza, Que la vida es una sola, Voy a reír, voy a bailar, Vive, sigue, Siempre pa'lante (Vivir Mi Mida - Marc Anthony)

Music: http://www.youtube.com/watch?v=YXnjy5YlDwk

3 comentarios:

Libin Huang dijo...

20160509libinralph lauren outlet
pandora outlet
tiffany outlet
nike huarache
ralph lauren polo
asics
camisetas futbol baratas
basketball shoes,basketball sneakers,lebron james shoes,sports shoes,kobe bryant shoes,kobe sneakers,nike basketball shoes,running shoes,mens sport shoes,nike shoes
cheap nfl jersey
fitflops clearance
timberland boots
michael kors outlet
louis vuitton pas cher
rolex watches for sale
tory burch outlet
adidas wings
coach outlet
michael kors uk
juicy couture outlet
fitflops uk
ralph lauren polo shirts
longchamp solde
tory burch outlet
cazal outlet
toms shoes
ralph lauren outlet
true religion outlet
cazal sunglasses
swarovski outlet
longchamp handbags
michael kors outlet sale
oakley sunglasses
cheap football shirts
longchamp pas cher
adidas trainers

Gege Dai dijo...

hermes belt for sale
ghd hair straighteners
christian louboutin uk
mulberry handbags sale
puma shoes
coach outlet online
cartier watches
coach outlet online
tods shoes
fitflops uk
beats by dr dre
adidas shoes
coach outlet
ray-ban sunglasses
rolex watches for sale
air max uk
calvin klein underwear
michael kors outlet online
hermes outlet store
coach outlet online
burberry sunglasses on sale
michael kors handbags
fitflops shoes
kate spade uk outlet
polo ralph lauren
coach outlet
michael kors outlet online
ralph lauren outlet
cheap jordans
lululemon pants
ray ban sunglasses sale
camisetas futbol baratas
coach outlet
fred perry polo
polo ralph lauren outlet
czq20160722

raybanoutlet001 dijo...

adidas nmd
jordans for cheap
tiffany jewelry
fitflops sale
adidas nmd runner
tiffany and co uk
mlb jerseys
discount oakley sunglasses
adidas tubular x
michael kors factory outlet
tiffany and co outlet online
coach outlet online
ray ban sunglasses outlet
ray ban sunglasses
air jordans,cheap air jordans,air jordan shoes,air jordan 11,air jordan 13,air jordan 6,air jordan 4
adidas nmd for sale
michael kors outlet
yeezy boost
michael kors outlet store
cheap rolex watches
tiffany jewelry
adidas stan smith men
air jordan shoes

Donate If You Can and Find Post Useful