Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 10 Next »

Context:

This proposal is to add support for

  1. Transforms between different models
  2. Mixins, includes
  3. Well-defined construction rules
  4. Extending of pom with additional meta-data

Solution 

There are two types of developers that will be interested in the project builder: 

  1. Framework Developer: a developer that extends data models, creates new transforms or creates new data models
  2. User: a developer who uses the framework to read models and interpolate values

We will address each separately.

Framework Developer

For new models, the framework developer will need to create a class that implements the ModelTransformer interface. The ModelTransformer.transformToDomainModel instance transforms a specified list of model properties (the canonical data model) into a single domain model. The list may contain a hierarchy (inheritance) of model information. In the case of PomClassicDomainModel, the returned DomainModel instance is a wrapper for the maven model. ModelTransformer.transformToModelProperties instance reverses the process of transforming the domain models to the canonical format of model properties. Thus the framework developer is responsible for doing bi-directional transform between data models and the canonical data model.

ModelTransformer Interface

The second interface that the framework developer is required to implement is the ModelContainer. This is implemented for any part of the model which is a collection.

ModelContainer Interface

The ModelContainer.containerAction implementation instance is required to return model container action (noop, delete, join) for the specified model container. For example, the following implementation says that if the group id and artifact id are the same but the version is different then delete the passed in container. If the group id, artifact id and version are the same, then join the containers. If the group id or artifact id are different, the don't do anything. 

ModelContainer.ContainerAction

The framework developer doesn't need to worry about any other mechanics; just transforming and determining the model action.

User

The user only needs to concern themselves with three classes: DomainModel, ModelTransformer and ModelTransformerContext. The DomainModel and ModelTransformer are implemented by framework developers so the user needs to obtain these instances through whatever means the framework developer has specified. They then use the ModelTransformerContext passing in the transformers and domain models to the ModelTransformerContext.transform method. They will get back the fully processed domain model.

ModelTransformerContext

In the case of transforming from say pom classic domain model to pom classic domain model, the instance passed in as fromModelTransformer and toModelTransformer parameters will be same. If transforming from say pom class domain model to pom model with attributes domain model, different transformers will be used for each parameter. Thus the user can change the type of returned DomainModel depending on the toModelTransformer instance.

General Sorting

The framework assigns each field within the pom a URI key and a value, which may be null. The following is an example of a model property list where the ordering from parent to child model is: [C, B, A]. All processing is done on this canonical model.

A
B
C

The framework would do an initial sort of the concatenated list, with the following rules:

(1) If there is any duplicate URI that does not contain a #collection, only the first URI will be maintained in the list.
(2) If there is any duplicate URI that ends in collection, only the first URI will be maintained in the list.
(3) If a URI contains a #collection in its direct parent of the URI tag, it will be placed directly after the parent.

In the sort, (3) will reverse the dependency list of collections so that the most general model element will be first under the collection. For example, org.apache.maven.dep:artificat-dep:1.4, which is from pom C, would first in the dependency management collection.


Processing Collections

The ModelDataSource contains the underlying list of ModelProperties (canonical data model). After the initial sort (above), all modifications of the data model go though the ModelDataSource class implementation instance. The ModelDataSource handles deleting and joining of ModelContainers, more specifically the deleting and joining of the ModelProperties that the ModelContainers contain.

ModelDataSource

After the general sorting, the framework finds each collection URI (has a #collection in the URI) and obtains the collection's ModelContainers by invoking ModelDataSource.queryFor(uri). The framework then does a comparison using ModelContainer.containerAction to determine whether the ModelContainer should be joined or deleted. The framework then invokes the appropriate actions on the ModelDataSource.

Interpolation

Interpolation comes after sorting and merging the inheritence tree.To interpolate a property, say ${project.artifactId} requires scanning the list of model properties for the URI: http://apache.org/model/project/artifactId and obtaining the value. Thus there is easy mapping between URIs and project properties, without the need of reflection.
(1) Timestamp policy: scan list for values with ${build.timestamp} replacing values
(2) Build property policies:

* ${build.directory}
* ${build.outputDirectory}
* ${build.testOutputDirectory}
* ${build.sourceDirectory}
* ${build.testSourceDirectory}
* ${build.scriptSourceDirectory}
* ${reporting.outputDirectory}
* ${basedir}

First, the values of the respective URIs are resolved. If any of the above property values do not reference another property, then their absolute path is resolved and placed back in as the value. For example:

Uri = http://apache.org/model/project/build/outputDirectory, Value = target

Would resolve to:

Uri = http://apache.org/model/project/build/outputDirectory, Value = C:\project\moduleA\target

If the property references another property then the other property is resolved first.

(3) UserProperty (command line values) policy: scan list for URIs that map to user property values.
(4) Environmental policy: scan list for values containing  ${env.*} and replacing them
(5) Model Property policy: scan list for any remaining values containing ${project.*} and replacing them
(6) Illegal values policies: scan list for any illegal values (self-referential)
(7) System property policy

Rules

General Rules:

(1) If it is a singleton URI (one per model) with a value, then the most specialized model value will be used.

(2) If it is a singleton URI node with no value and does not contain #collection in the URI, children will be joined. (A v B)/(A & B). If there are multiple values in the inheritence, the operation is applied from most specialized to least specialized model, meaning most specialized values take precedence.

(3) If it is a singleton URI node with no value but containing #collection in the URI, all values will initially be joined: (A v B). ModelContainer rules may be applied to handle duplicates.

There are 43 collections within the pom model that are sorted according to the general collection rules

Collections (Pom)
Model Container Rules

Processing order: 

  1. If a profile is active, the elements will be placed with precendence within the model property list. For example, if the profile contains an artifact with a different version than in the pom.dependencies.dependency, the artifact version within the profile will override the one within the primary pom. In short, this means that profile information is the most specialized model within the inheritence chain. Also the profiles will also be inherited from parent poms (and possibly joined). 
  2. For (A), (C-F), : values will be joined and deleted, with the most specialized model taking precedence. Any subcontainers like Plugin.Executions will also be joined based on equivalent ids.
  3. PluginManagement: Any PluginContainer that does not contain a version, will be joined with the PluginManagementContainer that contains the same artifactId and groupId. Any dependencies within the PluginContainer will also be joined or deleted according to the DependencyContainer.
  4. DependencyManagement: Any DependencyContainer that does not contain a version, will be joined with the DependencyManagementContainer that contains the same artifactId and groupId. 
  5. Interpolation of values 

Each collection in the model may need a ModelContainer implementation. The following rules apply:

  1. project/build/resources#collection
    No joins, just add additional resource tags. No container needed.
  2. project/build/testResources#collection
    No joins, just add additional testResource tags. No container needed.
  3. project/build/plugins#collection
    If groupId, artifactId and version are equals then join. If only groupId, artifactId are the same, but version is different, delete last container.
  4. project/build/plugins/plugin/dependencies#collection
    If groupId, artifactId and version are equals then join. If only groupId, artifactId are the same, but version is different, delete last container.
  5. project/build/plugins/plugin/dependencies/dependency/exclusions#collection
    No joins, just add additional exclusion tags. No container needed.
  6. project/build/plugins/plugin/executions#collection
    Joined if ids are the same, otherwise additional execution tag is added.
  7. project/build/extensions#collection
    No joins, add extension provided any of artifactId, groupId and version are different.
  8. project/build/pluginManagement/plugins#collection
    If groupId, artifactId and version are equals then join. If only groupId, artifactId are the same, but version is different, delete last container.
  9. project/build/pluginManagement/plugins/plugin/dependencies/dependency/exclusions#collection
    No joins, just add additional exclusion tags. No container needed.
  10. project/build/pluginManagement/plugins/plugin/executions#collection
    Joined if ids are the same, otherwise additional execution tag is added.
  11. project/build/pluginManagement/plugins/plugin/dependencies#collection
    If groupId, artifactId and version are equals then join. If only groupId, artifactId are the same, but version is different, delete last container.
  12. project/dependencyManagement/dependencies#collection
    If groupId, artifactId and version are equals then join. If only groupId, artifactId are the same, but version is different, delete last container.
  13. dependencyManagement/dependencies/dependency/exclusions#collection
    No joins, just add additional exclusion tags. No container needed
  14. project/dependencies/dependency/exclusions#collection
    No joins, just add additional exclusion tags. No container needed
  15. project/dependencies#collection
    If groupId, artifactId and version are equals then join. If only groupId, artifactId are the same, but version is different, delete last container.
  16. project/pluginRepositories#collection
    Joined if ids are the same, otherwise additional pluginRepository tag is added.
  17. project/repositories#collection
    Joined if ids are the same, otherwise additional repository tag is added.
  18. project/licenses#collection
    No joins, just add additional license tags. No container needed
  19. project/reporting/plugins#collection
    If groupId, artifactId and version are equals then join. If only groupId, artifactId are the same, but version is different, delete last container.
  20. project/reporting/plugins/plugin/reportSets#collection
    Joined if ids are the same, otherwise additional reportSet tag is added.
  21. project/contributors#collection
    No joins, just add additional contributor tags. No container needed
  22. project/developers#collection
    No joins, just add additional developer tags. No container needed
  23. project/mailingLists#collection
    No joins, just add additional mailingList tags. No container needed
  24. project/ciManagement/notifiers#collection
    No joins, just add additional notifier tags. No container needed
  25. project/profiles#collection
    Joined if ids are the same, otherwise additional profile tag is added.

All other profile collections/containers are processed according to their respective rules above.

Transforming Between Models

Transforming between XML based models involves changing the URIs. For example to change between the canonical model (which is based on the pom) and a C# project file, you would rename the URIs.

Canonical Model (Pom)
C# Project File

You can then have a standard marshaller that knows how to handle mapping of URIs to XML tags do the output of the C# project file. Since we are using a canonical data model, we can also do transforms between any models. For example, if say there exists bidirectional transforms from

(1) Model A to canonical model

(2) Model B to canonical model

and then I add my own

(3) model C to canonical model

then I can do transforms A<>C, B<>C, even though I know nothing about A and B models.

Extending Models

You can easily add information to the canonical model by defining new URIs. For example, we could introduce toolchains:

Toolchain Extension

Since the standard pom model transformer doesn't recognize the toolchain URI, it ignores it, keeping compatibility. However, an extended pom model implementation could read the toolchain info and expose it to the application.

Versioning Models

Versioning can be handled between the canonical models by introducing a version with the URIs:

Uri = http://apache.org/model/project/v1

The would allow the framework to easily detect the model and handle the URIs differently.

Extending This Framework

This existing framework is general enough to support other canonical data models (like the assembly descriptor). All the sorting and model data source operations are the same. Supporting new models with a new canonical data format requires news ModelContainer and new ModelTransformer implementations implementations that know how to process the format.

  • No labels