z2-Environment

h1. Maven Repos Support (MVNCR)

(#1696)

Maven repository can be integrated with Z2 as component repositories.

This is used for most of the [[Samples]] and [[Add-ons]] to access third-party binaries, so these are good examples. See [[Sample-hibernate-basic#How-this-sample-makes-use-of-MVNCR]] for a discussion on use of the MVNCR.

For Add-ons it is typical to rely on fragments (see below) to declare dependencies, and for a sample (or - of course - any actual solution) it is typical to declare a maven component repository to set the actual remote source of artifacts (and more).

h2. Principles

The main idea is that based on some root artifacts and some maven remote repository configuration, jar artifacts and dependencies will be made available as Java component in Z2 that can be referenced or included as suits best.

h2. Name mapping and version resolution

Artefacts in Maven repos have a fully qualified name of the form 

<pre>

<groupId>:<artifactId>:<version>

</pre>

or fully qualified, using a gradle-style syntax:

<pre>

<groupId>:<artifactId>:<version>:<classifier>@<packaging>

</pre>

Partial naming is possible. E.g. 

<pre>

com.atomikos:transactions-jta:6.0.0:jakarta

</pre>

For the 6.0.0 version of the Atomikos @transaction-jta@ library with "jakarta" classifier.

By default, an artifact @<groupId>:<artifactId>:<version>@ with "jar" packaging will result into a Java component of name 

<pre>

<groupId>:<artifactId>/java

</pre>

independently of its classifier. I.e. @com.atomikos:transactions-jta/java@ (or @com.atomikos:transactions-jta@ for short) in the case of the example above.

Any other packaging will lead to 

<pre>

<groupId>:<artifactId>/<packaging>

</pre>

Given that the resolution of the root artifacts and dependencies lead to artifacts of the same packaging, group id, and artifact id but with different versions the higher version number will be used (but see #1695).

h2. Example configuration

A maven repository component may look like this:

<pre><code class="ruby">

#

# we want to part of it

#

com.zfabrik.systemStates.participation=com.zfabrik.boot.main/process_up

#

# but only when all other repos are up

#

com.zfabrik.systemStates.dependency=com.zfabrik.boot.main/sysrepo_up

#

# it's a maven repo

#

com.zfabrik.component.type=com.zfabrik.mvncr

mvncr.priority=200

mvncr.roots=\

	org.springframework:spring-context:4.0.2.RELEASE,\

	org.springframework:spring-aspects:4.0.2.RELEASE,\

	org.springframework:spring-tx:4.0.2.RELEASE,\

	org.springframework:spring-orm:4.0.2.RELEASE,\

	org.springframework:spring-web:4.0.2.RELEASE,\

	org.springframework.security:spring-security-core:3.2.2.RELEASE,\

	org.springframework.security:spring-security-web:3.2.2.RELEASE,\

	org.springframework.security:spring-security-config:3.2.2.RELEASE,\

	org.springframework.security:spring-security-aspects:3.2.2.RELEASE,\

	org.hibernate:hibernate-entitymanager:4.3.4.Final,\

	aopalliance:aopalliance:1.0,\

	org.aspectj:aspectjweaver:1.7.4,\

	org.aspectj:aspectjtools:1.6.9,\

mvncr.excluded=\

        org.jboss.spec.javax.transaction:jboss-transaction-api_1.2_spec

mvncr.managed=\

        commons-logging:commons-logging:1.1.2

</code></pre>

By default, all non-optional compile scope dependencies will be resolved. The resulting Java component will have the target artifact as API library and all non-optional compile scope dependencies as public references in their mapped form.

The z2 core will use lazy component class loaders to make sure that use of include libraries has virtually no runtime penalty.

*NOTE* the state participation and dependency declaration. We want to make sure that other repositories, like file system, dev repo, git or subversion repositories are known to the system before we start maven resolution. We ask all other repositories to participate in sysrepo_up so that the declaration for the maven repository above makes sure this is happening. The reason this is important is that maven fragments (see below) may be supplied by other repositories. We want to make sure that all fragments are visible before the repository implementation commences dependency resolution.

h2. Component properties

|_. name |_. meaning |_. default |

| mvncr.settings | Specifies the location of the settings XML file relative to the components resources | settings.xml |

| mvncr.roots | A comman-separated list of root artifacts. See below for more details | n.a. |

| mvncr.priority | The repository priority in repository chaining as defined in IComponentsRepository | 500 |

| mvncr.managed	| Fixed artifact versions, if encountered during recursive root resolution. This corresponds to a <dependencyManagement> section in a Maven POM file | n.a. |

| mvncr.excluded | A comma separated list of artifacts that will be skipped during resolution of any root | n.a. | 

h2. Fine-Tuning of the Dependency Graph

In order to deviate from the default resolution and mapping, maven repository roots may be specified with a query string like this:

<pre>

	org.springframework.security:spring-security-aspects:3.2.2.RELEASE?versioned=true&scope=RUNTIME&excluded=commons-logging:commons-logging:1.1.2

</pre>

Admissable query params are 

|_. param |_. meaning |

| versioned | If set to @true@, the version part will not be removed from the java component name mapping and instead a versioned name is used. That is, in the case above, a java component @org.springframework.security:spring-security-aspects:3.2.2.RELEASE/java@ would be mapped. This is useful if "non-default" versions are required. |

| scope | Any of RUNTIME, COMPILE, PROVIDED, SYSTEM, TEST. Corresponds to the corresponding Maven dependency scopes. If set, non-optional dependencies of the respective scope will be traversed to resolve dependencies. |

| excluded | Exclusions on the dependency graph. |

h2. Handling the impact of PROVIDED references

At times, Maven provided artifacts require the presence of artifacts on the classpath that are expected to be required by the environment - most typically this is true for Web framework w.r.t the Servlet API.

In that case, it is simplest to create a Z2 project representation that includes all related artifacts (or include directly). In order to simplify this include process, includes may be specified to be transitively following Java component references by adding a corresponding query modifier to the include definition:

<pre>

java.publicIncludes=\

	com.vaadin:vaadin-server?expand=true

</pre> 

h2. Modularising Maven Dependencies

At times, it is useful to not have all required dependency roots in one component declaration but rather allow some modularization-friendly spread out declaration of dependency roots within a system. This is implemented by the *fragment* approach.

For example, an addon may define additional references, but in order to be reusable, it should not dictate what source to resolve those dependencies from. For example, this "mvnFragment":https://redmine.z2-environment.net/projects/z2-addons/repository/revisions/master/entry/com.zfabrik.springframework/mvnFragment.properties is the fragment of the [[Spring Add-on]]:

<pre>

#

# A fragment adding Maven dependencies

#

com.zfabrik.component.type=com.zfabrik.mvncr.fragment

#

# adds to default repository

#

mvncr.component=\

   environment/mavenDefault

mvncr.roots=\

	org.springframework:spring-context-support:4.0.2.RELEASE,\

	org.springframework:spring-context:4.0.2.RELEASE,\

	org.springframework:spring-aspects:4.0.2.RELEASE,\

	org.springframework:spring-tx:4.0.2.RELEASE,\

	org.springframework:spring-orm:4.0.2.RELEASE,\

        (....)

</pre>

Fragments are useful beyond separation of dependency and source repository separation. As conflict resolution will always happen within the scope of *one* Maven component repository, merging roots from different fragments for one repository is more consistent (in terms of conflict resolution) than having different maven repository declaration. In fact, in most cases having one Maven Component Repository will be the only manageable approach.

In order to add a _fragment_ to a Maven Component Repository declare a component of type *com.zfabrik.mvncr.fragment* with the following properties

|_. name |_. meaning |_. default |

| mvncr.component | The component name (or a comma-separated list of component names) of MVNCR declarations this fragment adds to or a fragment adding to some other mvncr | n.a. |

| mvncr.roots | As above. Will be merged with the repo this fragment adds to | n.a. |

| mvncr.managed	| As above. Will be merged with the repo this fragment adds to | n.a. |

| mvncr.excluded | As above. Will be merged with the repo this fragment adds to | n.a. |

h2. Development Support

When running in Development mode, the repository will also provide the source (classifier) artifact if available, so that the Eclipsoid plugins will provide source code attachments to the development environment whenever possible during classpath resolution. 

h2. References

* Main Javadoc: "MvnRepositoryResource":http://www.z2-environment.net/javadoc/com.zfabrik.mvncr!2Fjava/impl/com/zfabrik/impl/mvncr/MvnRepositoryResource.html

h2. To Dos

# Handling of SNAPSHOT-Versions to be revisited