Project

General

Profile

How to Access a Maven Repository » History » Version 20

Henning Blohm, 05.05.2014 08:30

1 19 Henning Blohm
h1. Maven Repos Support (MVNCR)
2 1 Henning Blohm
3 19 Henning Blohm
(#1696)
4 1 Henning Blohm
5 17 Henning Blohm
Maven repository can be integrated with Z2 as component repositories.
6 1 Henning Blohm
7 20 Henning Blohm
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.
8 18 Henning Blohm
9
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).
10
11 5 Henning Blohm
h2. Principles
12 1 Henning Blohm
13 5 Henning Blohm
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.
14
15
h2. Name mapping and version resolution
16
17 1 Henning Blohm
Artefacts in Maven repos have a fully qualified name of the form 
18
19
<pre>
20
<groupId>:<artifactId>:<version>
21
</pre>
22
23 5 Henning Blohm
or 
24 1 Henning Blohm
25 5 Henning Blohm
<pre>
26
<groupId>:<artifactId>:<packaging>:<version>
27
</pre>
28 1 Henning Blohm
29 5 Henning Blohm
By default, a jar artifact @<groupId>:<artifactId>:<version>@ will result into a Java component of name 
30 1 Henning Blohm
31
<pre>
32 5 Henning Blohm
<groupId>:<artifactId>/java
33 1 Henning Blohm
</pre>
34
35 5 Henning Blohm
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).
36 1 Henning Blohm
37 5 Henning Blohm
h2. Example configuration
38
39
A maven repository component may look like this:
40
41
<pre>
42
com.zfabrik.systemStates.participation=com.zfabrik.boot.main/sysrepo_up
43
com.zfabrik.component.type=com.zfabrik.mvncr
44 9 Henning Blohm
mvncr.priority=200
45
mvncr.roots=\
46
	org.springframework:spring-context:4.0.2.RELEASE,\
47 5 Henning Blohm
	org.springframework:spring-aspects:4.0.2.RELEASE,\
48
	org.springframework:spring-tx:4.0.2.RELEASE,\
49
	org.springframework:spring-orm:4.0.2.RELEASE,\
50
	org.springframework:spring-web:4.0.2.RELEASE,\
51
	org.springframework.security:spring-security-core:3.2.2.RELEASE,\
52
	org.springframework.security:spring-security-web:3.2.2.RELEASE,\
53
	org.springframework.security:spring-security-config:3.2.2.RELEASE,\
54
	org.springframework.security:spring-security-aspects:3.2.2.RELEASE,\
55 9 Henning Blohm
	org.hibernate:hibernate-entitymanager:4.3.4.Final,\
56 1 Henning Blohm
	aopalliance:aopalliance:1.0,\
57
	org.aspectj:aspectjweaver:1.7.4,\
58
	org.aspectj:aspectjtools:1.6.9,\
59 9 Henning Blohm
60
mvncr.excluded=\
61
        org.jboss.spec.javax.transaction:jboss-transaction-api_1.2_spec
62
63
mvncr.managed=\
64
        commons-logging:commons-logging:1.1.2
65 5 Henning Blohm
</pre>
66
 
67
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.
68
69
The z2 core will use lazy component class loaders to make sure that use of include libraries has virtually no runtime penalty.
70
71 13 Henning Blohm
h2. Component properties
72 6 Henning Blohm
73 13 Henning Blohm
|_. name |_. meaning |_. default |
74
| mvncr.settings | Specifies the location of the settings XML file relative to the components resources | settings.xml |
75
| mvncr.roots | A comman-separated list of root artifacts. See below for more details | n.a. |
76
| mvncr.priority | The repository priority in repository chaining as defined in IComponentsRepository | 500 |
77
| mvncr.managed	| Fixed artifact versions, if encountered during recursive root resolution. This corresponds to a <dependencyManagement> section in a Maven POM file | n.a. | 
78
| mvncr.excluded | A comma separated list of artifacts that will be skipped during resolution of any root | n.a. | 
79
80 5 Henning Blohm
h2. Fine-Tuning of the Dependency Graph
81 9 Henning Blohm
82 5 Henning Blohm
In order to deviate from the default resolution and mapping, maven repository roots may be specified with a query string like this:
83 1 Henning Blohm
84
<pre>
85 5 Henning Blohm
	org.springframework.security:spring-security-aspects:3.2.2.RELEASE?versioned=true&scope=RUNTIME&excluded=commons-logging:commons-logging:1.1.2
86 1 Henning Blohm
</pre>
87
88 13 Henning Blohm
Admissable query params are 
89 1 Henning Blohm
90 13 Henning Blohm
|_. param |_. meaning |
91
| 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. |
92
| 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. |
93
| excluded | Exclusions on the dependency graph. |
94 6 Henning Blohm
95
h2. Handling the impact of PROVIDED references
96
97
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.
98 8 Henning Blohm
99 1 Henning Blohm
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:
100
101
<pre>
102
java.publicIncludes=\
103 6 Henning Blohm
	com.vaadin:vaadin-server?expand=true
104 9 Henning Blohm
</pre> 
105 12 Henning Blohm
106 14 Henning Blohm
h2. Modularising Maven Dependencies
107
108
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. 
109
110
Note that having two sets of roots combined and resolved is not equivalent to having to independent Maven Component Repository declaration as version conflict resolution (to the higher version) will always happen within the scope of one Maven component repository. In fact, in most cases having one Maven Component Repository will be the only manageable approach.
111
112
In order to add a _fragment_ to a Maven Component Repository declare a component of type *com.zfabrik.mvncr.fragment* with the following properties
113
114
|_. name |_. meaning |_. default |
115 16 Henning Blohm
| 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. |
116 14 Henning Blohm
| mvncr.roots | As above. Will be merged with the repo this fragment adds to | n.a. |
117
| mvncr.managed	| As above. Will be merged with the repo this fragment adds to | n.a. | 
118
| mvncr.excluded | As above. Will be merged with the repo this fragment adds to | n.a. | 
119
120
121 12 Henning Blohm
h2. Development Support
122
123
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. 
124 9 Henning Blohm
125
h2. References
126 10 Henning Blohm
127 7 Henning Blohm
* Main Javadoc: "MvnRepositoryResource":http://www.z2-environment.net/javadoc/com.zfabrik.mvncr!2Fjava/impl/com/zfabrik/impl/mvncr/MvnRepositoryResource.html
128
129
h2. To Dos
130
131 1 Henning Blohm
# Handling of SNAPSHOT-Versions to be revisited