Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: for the plan.

Jump to: navigation, search


< Gendoc
Revision as of 13:28, 16 February 2017 by (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


The goal of the example is creating a tag named "Properties" which allows the registration of parameters using properties file.

The properties file will be referenced through an attribute named "path". This attribute would be able to contain reference to gendoc variables (${project_loc}, ${input_directory}....).

This example is a real use case already contributed to gendoc.


Open a bug

first step is to create a new Bug categorized as an enhancement. In our example the created bug is :


The code source of this example can be visible through these 2 gerrit contributions :

Global Idea

The good way to create a tag in gendoc is :

  • create a handler (implements org.eclipse.gendoc.tags.ITagHandler) which analyze the tag
  • create a service (extends or implements which will do business work

It is a common practice in gendoc to separate handlers and services

  • Services can be overridden by developers so initial behavior can be changed
  • It forces the developer to separate the analysis of the tag and the business code


Fill the extension : org.eclipse.gendoc.serviceTypes

  • id : the ID of your service in our case : PropertiesService
  • interface : the contract of the service : org.eclipse.gendoc.tags.handlers.IPropertiesService

Create the Interface org.eclipse.gendoc.tags.handlers.IPropertiesService

  • it inherits from

The interface contains only one method : void setPropertiesFile (File file) which loads a properties file and fill the gendoc parameters with the properties file content

Fill the extension :

  • default : true
  • class : the implementation of the interface :
  • id : an ID which reference your instance : DefaultPropertiesService
  • serviceType : the implemented service type : PropertiesService

Create the implementation :

/!\ generally implementations of services are not exported to other plugins

public class PropertiesServices extends implements org.eclipse.gendoc.tags.handlers.IPropertiesService

This service will : - check if the extension is properties - read the properties file in parameter with the correct charset - for each entry in the properties file will register a parameter to gendoc (with a correct substitution of potential usage of existing parameter) [1]

[1] :

Properties p = new Properties();


IConfigurationService config = GendocServices.getDefault().getService(IConfigurationService.class);

for (Entry<Object,Object> e : p.entrySet()){

    if (e.getKey() instanceof String && e.getValue() instanceof String){
        config.addParameter((String)e.getKey(), config.replaceParameters((String)e.getValue()));


Tag Handler

  • Fill the extension : org.eclipse.gendoc.tags to create new tag
    • the tag contains one attribute : "path" which is required and typed java.lang.String
    • reference a class you will create :

Some mechanisms exist in gendoc to plug operation on tag analysis, to automatically get them our class inherits from org.eclipse.gendoc.tags.handlers.impl.AbstractServicesTagHandler

The methods to implement in are doRun and runAttributes.

- doRun is the method called to run a tag. ie when the content of the tag is replaced by a new content. In the properties case we want to remove the content so we only have to return an empty String :

public String doRun(ITag tag) throws GenDocException {

   return "";


- runAttributes is the method called when the attributes are analyzed.

In our case the runAttributes method will :

 - replace parameters (like project_loc) [1]
 - check if the file exists (and raise an error if it is not the case) [2]
 - call the PropertiesService to load and process the properties file [3]

/!\ In this example the parameters replacement and the file check are made in tag handler. It could be moved to the Service if you want to have tag easier to override.

protected String runAttributes(ITag tag, String value) throws GenDocException


// [1]

for (String key : tag.getAttributes().keySet()) {

   if (RegisteredTags.PROPERTIES_PATH.equalsIgnoreCase(key)){
       IConfigurationService configService = GendocServices.getDefault().getService(IConfigurationService.class);
       String path = configService.replaceParameters(tag.getAttributes().get(key));


// [2]

IGendocDiagnostician logger = GendocServices.getDefault().getService(IGendocDiagnostician.class);

logger.addDiagnostic(IStatus.ERROR,"file containing properties : " + path + " does not exist", null);


// [3]

IPropertiesService propertiesService = GendocServices.getDefault().getService(IPropertiesService.class);



To test, a template can be filled with this tag :

  • <properties path='${input_directory}/' />

with containing :

  • base_dir=${input_directory}/output
  • input_model=c:/your_model_path/model.uml
  • output_path_generation=${base_dir}/output-${date}.docx

and the variables can be used in the template :


   <output path='${output_path_generation}'/>


<context model='${input_model}' />

Back to the top