Project

General

Profile

Vaadin Add-on » History » Version 12

Henning Blohm, 02.03.2020 22:00

1 1 Henning Blohm
h1. The Vaadin Add-on
2
3 11 Henning Blohm
The Vaadin add-on provides access to Vaadin libraries from Maven repositories and some supporting functions for best use of Vaadin in conjunction with Z2:
4 1 Henning Blohm
5 2 Henning Blohm
* The *ContextClassLoader* ("source":https://redmine.z2-environment.net/projects/z2-addons/repository/z2-addons-vaadin/revisions/master/entry/com.vaadin/java/src.api/com/zfabrik/vaadin/ContextClassLoader.java, "javadoc":http://www.z2-environment.net/javadoc/com.vaadin!2Fjava/api/com/zfabrik/vaadin/ContextClassLoader.html) utility helps loading your Vaadin application class from the right context.
6 4 Henning Blohm
* An extensibility utility. The *ExtensionComponentsUtil* ("source":https://redmine.z2-environment.net/projects/z2-addons/repository/z2-addons-vaadin/revisions/master/entry/com.zfabrik.vaadin/java/src.api/com/zfabrik/vaadin/ExtensionComponentsUtil.java, "javadoc":http://www.z2-environment.net/javadoc/com.zfabrik.vaadin!2Fjava/api/com/zfabrik/vaadin/ExtensionComponentsUtil.html) help you to split a Vaadin web application across modules.
7 1 Henning Blohm
8
The sample [[Sample-Vaadin-Spring-Hibernate]] makes use of both features.
9 11 Henning Blohm
10
h2. Repository
11
12
"z2-addons-vaadin":http://redmine.z2-environment.net/projects/z2-addons/repository/z2-addons-vaadin
13
14
h2. Version map
15
16 12 Henning Blohm
|_. add-on version |_. Vaddin version |
17 11 Henning Blohm
| 2.2 | 6.8.4 |
18 1 Henning Blohm
| 2.3 | 7.1.2 |
19 12 Henning Blohm
| 2.4 | 7.1.2 |
20
| 2.5 | 7.1.2 |
21
| 2.6 | 7.1.2 |
22
| 2.7 | 7.1.2 |
23
| 2.8 | 7.1.2 |
24
25 10 Henning Blohm
26 1 Henning Blohm
h2. More details on the ContextClassLoader
27
28 4 Henning Blohm
In non-modular application environments like the typical Java Web Application Server, you will typically use a build tool like ANT or Maven to package all libraries and resources that are required to run your Web application into one Web application archive (WAR). At runtime, a Web container like Apache Tomcat serves all code-like resources of the Web app from one classloading scope. 
29
30
Toolkits like Vaadin that need to load user classes by name now need to decide what class loader to refer to for loading of user-defined classes, such as the actual application class in the Vaadin case. The right and de-facto standard choice is to use the context class loader associated with the current thread. Unfortunately Vaadin uses the class loader that loaded the Vaadin classes however. 
31
32
In modular environments, such as Z2 but also OSGi, the Vaadin implementation will typically be shared among many Web applications. In that case, the application may see the Vaadin types but not vice versa.
33
34
In order to make Vaadin work as expected, add the following init parameter to the Vaadin servlet config in the @web.xml@ file of your Web app:
35
36
<pre><code class="xml">
37
<init-param>
38
	<param-name>ClassLoader</param-name>
39
	<param-value>com.my.package.ContextClassLoader</param-value>
40
</init-param>
41
</code></pre>
42
43
Read on here:
44
* "web.xml":https://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-vaadin-spring-hibernate/revisions/master/entry/com.zfabrik.samples.vaadin-spring-hibernate.web/web/WebContent/WEB-INF/web.xml of Vaadin sample app
45
* "Ticket":http://dev.vaadin.com/ticket/9809 with Vaadin
46
* A "blog article":http://www.z2-environment.net/blog/2012/07/for-techies-protecting-java-in-a-modular-world-context-classloaders/ on class loader topics
47 1 Henning Blohm
48
h2. More details on the ExtensionComponentsUtil
49 5 Henning Blohm
50
While the context class loader from above is a necessity to use Vaadin, the extension components util (ECU) is a great but not strictly required addition. It implements the following formula
51
52 6 Henning Blohm
(Vaadin is all Java) + (Z2 for modular Java applications) => Modular Vaadin user interfaces on Z2
53 5 Henning Blohm
54 1 Henning Blohm
More specifically, when applications get bigger, user interface implementations, like other parts of your implementation, have a tendency to become too big to maintain as single, monolithic modules. Using the ECU you can rather easily break your user interface implementation into modules that may have their completely private set of dependencies. This does not only allow to split the code base into well-managable pieces, it does also allow to cleanly separate concerns and to implement general user interface extensibility.
55 6 Henning Blohm
56
h3. Doing it
57
58
The extension component, that will be retrieved by the to-be-extended Vaadin UI must declare the extension point it belongs to and some priority, e.g. like this:
59
60
<pre><code class="bash">
61
com.zfabrik.vaadin.extension.point=com.acme.sample.admin.mainTab
62
com.zfabrik.vaadin.extension.order=100
63
</code></pre>
64
65 9 Henning Blohm
The extension point id is used to find it (see below). The order is used to sort extensions before returning them as an ordered collection to the consumer. The latter can be useful, for example, to define the order of tab panels in a tab layout.
66 6 Henning Blohm
67 8 Henning Blohm
From a consumer perspective, i.e. from the retrieving party, the component implements the *IExtensionComponentFactory* ("source":https://redmine.z2-environment.net/projects/z2-addons/repository/z2-addons-vaadin/revisions/master/entry/com.zfabrik.vaadin/java/src.api/com/zfabrik/vaadin/IExtensionComponentFactory.java, "javadoc":http://www.z2-environment.net/javadoc/com.zfabrik.vaadin!2Fjava/api/com/zfabrik/vaadin/IExtensionComponentFactory.html) interface. 
68 6 Henning Blohm
69 8 Henning Blohm
Using the *ExtensionsComponentUtil* the consuming side can then simply retrieve and bind extension components like this:
70 6 Henning Blohm
71
<pre><code class="java">
72
// retrieve all Vaadin components for extension point "com.acme.sample.admin.mainTab"
73
for (Component c : ExtensionComponentsUtil.getComponentyByExtensionForApplication(application,"com.acme.sample.admin.mainTab")) {
74 1 Henning Blohm
   // and add them to this.
75
   addComponent(c);
76
}
77
</code></pre>
78
79 8 Henning Blohm
For the providing side, two possibilities exist: 
80 1 Henning Blohm
81 8 Henning Blohm
For once, a component may be declared of type *com.vaadin.ui.Component* (implemented by "ExtensionComponentResource":http://www.z2-environment.net/javadoc/com.zfabrik.vaadin!2Fjava/impl/com/zfabrik/impl/vaadin/ExtensionComponentResource.html). In that case, the class specified via the *component.className* property can either implement directly Vaadin's Component interface or the more explicit provider interface *IExtensionComponent* ("javadoc":http://www.z2-environment.net/javadoc/com.zfabrik.vaadin!2Fjava/api/com/zfabrik/vaadin/provider/IExtensionComponent.html).  
82
83
The former is simpler and safes one implementation class. In many cases, Vaadin Component implementations require the current Vaadin application at creation time. For convenience, if the implementation class specified has a single argument constructor accepting a Vaadin application instance, that constructor will be used with preference and the application object of the retrieving user interface will be passed.
84
85
In the latter case, an extension component implementation may check for pre-conditions on the application object passed into "IExtensionComponent.html#createNewInstanceForApplication(com.vaadin.Application)":http://www.z2-environment.net/javadoc/com.zfabrik.vaadin!2Fjava/api/com/zfabrik/vaadin/provider/IExtensionComponent.html#createNewInstanceForApplication%28com.vaadin.Application%29 before actually instantiating a control instance. 
86 1 Henning Blohm
87 9 Henning Blohm
A complete extension component declaration looks like this:
88
89
<pre><code class="bash">
90
#
91
# A Vaadin UI extension 
92
#
93
com.zfabrik.component.type=com.vaadin.ui.Component
94
95
#
96
# Coordinates:
97
#
98
com.zfabrik.vaadin.extension.point=com.acme.admin.mainTab
99
com.zfabrik.vaadin.extension.order=100
100
101
#
102
# The implementation class
103
#
104
component.className=com.acme.admin.impl.UsersTab
105
</code></pre>
106 8 Henning Blohm
107
108
Alternatively to using the custom Vaadin Component type above, a component of any origin (e.g. a Spring bean) should simply implement *IExtensionComponentFactory* ("javadoc":http://www.z2-environment.net/javadoc/com.zfabrik.vaadin!2Fjava/api/com/zfabrik/vaadin/IExtensionComponentFactory.html) and adhere to its contract.