Apache MyFaces
Project Documentation
Foundation

myfaces-builder:build-metadata

Maven goal which runs one or more ModelBuilder objects to gather metadata about JSF artifacts into a Model object, then save that model object as an xml file for use by other goals of this plugin.

By default, the generated file is named "META-INF/myfaces-metadata.xml". This file will be included in the final artifact for this project. Having that metadata file embedded in the generated jarfile is useful for two purposes:

  • It is needed if other projects then use the myfaces-builder-plugin to create subclasses of the jsf classes in this project.
  • It is good documentation (more precise than the tld and faces-config.xml files).

Note that the generated file contains all the metadata needed by this project, including a copy of all the metadata from other projects that this one depends on. All other goals of this plugin can execute with just the generated metadata as input, without needing to load other projects. Each entry in the metadata is labelled with a "modelId" property that indicates where it originally came from.

Mojo Attributes:

  • Requires a Maven 2.0 project to execute.
  • Requires dependency resolution of artifacts in scope: compile
  • Automatically executes within the lifecycle phase: generate-sources

Optional Parameters

Name Type Description
compositeComponentDirectory File The directory where there are the composite component templates
compositeComponentLibraries Map Indicate the composite libraries to be loaded in the form of <short-name>libraryName</short-name> .
dependencyModelIds List An optional list of models to import from dependency jars.

The default behaviour is to scan all jar dependencies for metadata files, and merge all the data into the model for this project. If this property is set, then metadata found in dependencies is only merged if the modelId matches one in this list.

Note that by default, a project's modelId is the same as the artifactId.

excludes String A comma separated list of file patterns to exclude when building the model. i.e. **\/*.java
generatedSourceDirectory File The directory where all generated files are created. This directory is added as a compile source root automatically like src/main/java is.
includes String A comma separated list of file patterns to include when building the model. i.e. **\/*.java
inputFile File The name of a metadata file to merge into the model for the current project.

This file is always loaded first, before any metadata from dependencies is loaded, and before scanning of the source directories for the current project is done.

The specified filename is relative to the current working directory.

Normally, this option is not used and any models that this project extends are simply automatically detected via scanning of the maven dependencies and loaded from the dependency jarfile. However there are a couple of situations where it is useful to specify an explicit metadata file to load instead.

One example is when a project extends components in a project which was not built with the myfaces-builder-plugin (or where myfaces-builder-plugin support is only in a not-yet-released version). In this case, a metadata file can be created by hand (or generated from the unreleased trunk version) and explicitly loaded via this property.

A second example is when it is necessary to add some custom model definitions to the model to be built, eg to override buggy or missing metadata in a project that this project extends. Of course this is hopefully not needed; it would be better to get a bugfix release of the parent project out instead!

modelId String The modelId to associate with all model items discovered in the source directories of this project.

This value must be unique for each project. If not specified, then it defaults to the artifactId of the current maven project.

In later phases, goals are passed the complete metadata model which mixes items discovered here with items imported from metadata in other projects. The modelId is used to figure out which of the items should be processed (ie which ones are associated with this project) and which should be ignored.

orderModelIds List Specify the order in which models are to be merged (not usually needed).

When two different models define exactly the same item (ie the "class" attribute for two items is the same) then the one from the model that is merged first is used, and the later one is ignored.

This property allows the order of merging to be controlled; models are merged in the order specified in this list. Any models whose ids are not in this list are then merged in an undefined order at the end.

Setting this property is not normally necessary; typically models inherited from dependencies define different model items (ie have no overlap). However consider the situation where project A defines a model, project B extends A, then project C extends B. In this case, both A and B are in the dependencies, but the metadata in project B contains a complete copy of all the data from A. However B's metadata is from the version of A that it was compiled against which might not be the version of A that is in the dependencies. For safety in this case, it is better to ensure that project B's metadata is loaded first; this can possibly hide any new features (or bugfixes) from the new release of A, but also ensures that classes in C which extend classes in B do not declare features that B does not support.

This property is only needed in rare situations; normally it can be omitted.

outputFile String Name of the metadata file to generate, relative to targetDirectory.
readMavenFacesPluginMetadata String Indicate that metadata is provided in the structure of trinidad maven-faces-plugin faces-config.xml files and should be feed to build the full metadata information of this jar file.
replacePackagePrefixTagFrom String Replace the package prefix.

This allows a project that inherits metadata from some other project to force copies of the Tag classes to be created in a namespace of its own choosing.

This is used in particular to create copies of the Tag classes in myfaces-impl within other projects so that they can be used as base classes for other tags within that project. The original tag present in the myfaces-impl.jar cannot be used as a base because that would prevent the derived project from running with other JSF implementations.

The child project first defines this (and replacePackagePrefixTagTo); as the inherited metadata is merged the tagClass attribute is modified. Then during the tag class generation goal, the modelId of the inherited project is included in the list of modelIds to process. That causes the tag classes to be generated again - but this time in a different package.

replacePackagePrefixTagTo String Replace the package prefix

See replacePackagePrefixTagTo.

sourceDirectories List This param is used to search in this folder if some file to be generated exists and avoid generation and duplicate exception.
targetDirectory File Build directory for all generated stuff.

This mojo registers the specified directory with Maven as a resource dir. The maven-resources-plugin will then read the files from this dir and copy them into the "central" target directory from which the jarfile is built.

Parameter Details

compositeComponentDirectory

The directory where there are the composite component templates

  • Type: java.io.File
  • Required: No
  • Expression: src/main/resources/META-INF/resources

compositeComponentLibraries

Indicate the composite libraries to be loaded in the form of <short-name>libraryName</short-name> .

  • Type: java.util.Map
  • Required: No

dependencyModelIds

An optional list of models to import from dependency jars.

The default behaviour is to scan all jar dependencies for metadata files, and merge all the data into the model for this project. If this property is set, then metadata found in dependencies is only merged if the modelId matches one in this list.

Note that by default, a project's modelId is the same as the artifactId.

  • Type: java.util.List
  • Required: No

excludes

A comma separated list of file patterns to exclude when building the model. i.e. **\/*.java

  • Type: java.lang.String
  • Required: No

generatedSourceDirectory

The directory where all generated files are created. This directory is added as a compile source root automatically like src/main/java is.

  • Type: java.io.File
  • Required: No
  • Expression: ${project.build.directory}/generated-sources/myfaces-builder-plugin

includes

A comma separated list of file patterns to include when building the model. i.e. **\/*.java

  • Type: java.lang.String
  • Required: No

inputFile

The name of a metadata file to merge into the model for the current project.

This file is always loaded first, before any metadata from dependencies is loaded, and before scanning of the source directories for the current project is done.

The specified filename is relative to the current working directory.

Normally, this option is not used and any models that this project extends are simply automatically detected via scanning of the maven dependencies and loaded from the dependency jarfile. However there are a couple of situations where it is useful to specify an explicit metadata file to load instead.

One example is when a project extends components in a project which was not built with the myfaces-builder-plugin (or where myfaces-builder-plugin support is only in a not-yet-released version). In this case, a metadata file can be created by hand (or generated from the unreleased trunk version) and explicitly loaded via this property.

A second example is when it is necessary to add some custom model definitions to the model to be built, eg to override buggy or missing metadata in a project that this project extends. Of course this is hopefully not needed; it would be better to get a bugfix release of the parent project out instead!

  • Type: java.io.File
  • Required: No

modelId

The modelId to associate with all model items discovered in the source directories of this project.

This value must be unique for each project. If not specified, then it defaults to the artifactId of the current maven project.

In later phases, goals are passed the complete metadata model which mixes items discovered here with items imported from metadata in other projects. The modelId is used to figure out which of the items should be processed (ie which ones are associated with this project) and which should be ignored.

  • Type: java.lang.String
  • Required: No
  • Expression: ${project.artifactId}

orderModelIds

Specify the order in which models are to be merged (not usually needed).

When two different models define exactly the same item (ie the "class" attribute for two items is the same) then the one from the model that is merged first is used, and the later one is ignored.

This property allows the order of merging to be controlled; models are merged in the order specified in this list. Any models whose ids are not in this list are then merged in an undefined order at the end.

Setting this property is not normally necessary; typically models inherited from dependencies define different model items (ie have no overlap). However consider the situation where project A defines a model, project B extends A, then project C extends B. In this case, both A and B are in the dependencies, but the metadata in project B contains a complete copy of all the data from A. However B's metadata is from the version of A that it was compiled against which might not be the version of A that is in the dependencies. For safety in this case, it is better to ensure that project B's metadata is loaded first; this can possibly hide any new features (or bugfixes) from the new release of A, but also ensures that classes in C which extend classes in B do not declare features that B does not support.

This property is only needed in rare situations; normally it can be omitted.

  • Type: java.util.List
  • Required: No

outputFile

Name of the metadata file to generate, relative to targetDirectory.

  • Type: java.lang.String
  • Required: No

readMavenFacesPluginMetadata

Indicate that metadata is provided in the structure of trinidad maven-faces-plugin faces-config.xml files and should be feed to build the full metadata information of this jar file.

  • Type: java.lang.String
  • Required: No

replacePackagePrefixTagFrom

Replace the package prefix.

This allows a project that inherits metadata from some other project to force copies of the Tag classes to be created in a namespace of its own choosing.

This is used in particular to create copies of the Tag classes in myfaces-impl within other projects so that they can be used as base classes for other tags within that project. The original tag present in the myfaces-impl.jar cannot be used as a base because that would prevent the derived project from running with other JSF implementations.

The child project first defines this (and replacePackagePrefixTagTo); as the inherited metadata is merged the tagClass attribute is modified. Then during the tag class generation goal, the modelId of the inherited project is included in the list of modelIds to process. That causes the tag classes to be generated again - but this time in a different package.

  • Type: java.lang.String
  • Required: No

replacePackagePrefixTagTo

Replace the package prefix

See replacePackagePrefixTagTo.

  • Type: java.lang.String
  • Required: No

sourceDirectories

This param is used to search in this folder if some file to be generated exists and avoid generation and duplicate exception.

  • Type: java.util.List
  • Required: No

targetDirectory

Build directory for all generated stuff.

This mojo registers the specified directory with Maven as a resource dir. The maven-resources-plugin will then read the files from this dir and copy them into the "central" target directory from which the jarfile is built.

  • Type: java.io.File
  • Required: No
  • Expression: ${project.build.directory}/generated-resources/myfaces-builder-plugin