Project

General

Profile

Wiki » History » Version 15

Henning Blohm, 23.01.2015 10:00

1 1 Henning Blohm
h1. Intro
2
3 2 Henning Blohm
This project is for the development of [[z2-environment:wiki|z2-environment]] version 3.0.
4 1 Henning Blohm
5 2 Henning Blohm
Version 3.0 is a major refactoring release of z2 with new repository code lines and complete package renaming.
6 1 Henning Blohm
7 2 Henning Blohm
h1. Essential Differences between v2.3 and v3.
8 1 Henning Blohm
9 2 Henning Blohm
* All the typical declarations and package names are no longer *com.zfabrik.<something>* but rather *org.z2env.<something>*
10 13 Henning Blohm
* The <z2 home> layout is completely new and more flexible
11 3 Henning Blohm
* The essential component types that can be _invoked_ from the core is *system state* and *main program*.
12 14 Henning Blohm
* While Jetty is still contained to support Eclipsoid and z2Unit, we support a pre-installed Tomcat as application container (and with TomEE would even get a Java EE profile)
13 1 Henning Blohm
* The core is lighter and more dedicated. 
14 12 Henning Blohm
* There will be substantially less built-in application support like
15
** a local JTA implementation 
16
** No worker suppport without a corresponding add-on.
17 1 Henning Blohm
18 12 Henning Blohm
The main task of v3 is:
19 13 Henning Blohm
* Make the lower parts of z2 more accessible and easier to understand: While z2 previously started System Centric, we now close the gap from the ordinary main program.
20 12 Henning Blohm
* Increase the OSS flavor of z2
21
22 15 Henning Blohm
Obvious TODOs:
23
* Finish Java 8 support
24
* Test TomEE
25
* Fix Eclipsoid templates
26
* Support MVNCR, also for distributions
27 12 Henning Blohm
28 9 Henning Blohm
h1. Draft Intro Documentation
29 1 Henning Blohm
30 2 Henning Blohm
h2. Getting Started
31 1 Henning Blohm
32 2 Henning Blohm
To understand how z2 works, you need to understand at most what are z2 modules and components and what are component repositories and how these concepts interplay. 
33 1 Henning Blohm
34 6 Henning Blohm
Check out [[wiki#Understanding-Z2|understanding-z2]] for that.
35 1 Henning Blohm
36 2 Henning Blohm
It is simplest to start by running a simple Java main program in z2 or a simple Web App. 
37 1 Henning Blohm
38 2 Henning Blohm
Follow this trail:
39 1 Henning Blohm
40 4 Henning Blohm
* [[wiki#Building-z2env-core|Building the core]]
41 7 Henning Blohm
* [[wiki#Running-a-Hello-World-main-program|Running a Hello World main program]]
42 10 Henning Blohm
* [[wiki#Running-a-Hello-World-Web-App|Running a Hello World Web App]]
43 1 Henning Blohm
44 3 Henning Blohm
h2. Building z2env-core
45 1 Henning Blohm
46 3 Henning Blohm
First clone http://git.z2-environment.net/z2env.core
47
48
<pre>
49
git clone http://git.z2-environment.net/z2env.core
50
</pre>
51
52
Switch into *org.z2env.core.main* and run 
53
54
<pre>
55 5 Henning Blohm
ant -Doutput=<location of z2 home> -Dsetup=<preconfigured roots> 
56 3 Henning Blohm
</pre>
57
58 5 Henning Blohm
where <location of z2 home> is where you want to install z2 (the <z2-home>) and <preconfigured roots> is a choice of pre-configured content, actually component repositories.
59 3 Henning Blohm
60
If you omit *output* it will default to *gen/dist*. If you omit *setup*, no content will be pre-configured will be modified. 
61
62
Check the folder *setups* for available setups of the core build. These can be local (all repos will be cloned locally) or remote (repos will be remoted).
63
64
In general this build always updates only boot, z.jar, roots. It will not remove anything.
65
66
Example to install/update a core only into ../../z2env:
67
68
<pre>
69
ant -Doutput=here 
70
</pre>
71
72
To install/update a web-basic setup (with tomcat and eclipsoid support) with updates from remote repos:
73
74
<pre>
75
ant -Doutput=../../z2env -Dsetup=web-basic-remote
76 1 Henning Blohm
</pre>
77 7 Henning Blohm
78
h2. Running a Hello World main program
79
80
For now, we will assume you have a z2 core installed in <HOME>. In its purest form, all the core can actually execute is simple Java main programs. 
81
82
Being in a modular environment, even if we only want to say „Hello World“, we need a module. Let's call it the greeter module. In order to have a main program run by z2, we need to also declare a  component for it, as that is what we tell z2 to run (not a class – mind you – but rather a component in a module). Assuming we use the local component name hello, than the absolut component name is 
83
84
<pre>
85
greeter/hello
86
</pre>
87
88
Finally, as this component actually has implementation code, we need to declare a Java component. By convention this is 
89
90
<pre>
91
greeter/java
92
</pre>
93
94
Now, after installing in <HOME> the place to simply drop a module is under <HOME>/modules. All in all, here is the complete structure to create:
95
96
| <HOME>/modules/greeter/hello.properties | 
97
<pre><code class="ruby">org.z2env.component.type=org.z2env.main
98
component.className=greetings.Main
99
</code></pre> |
100
| <HOME>/modules/greeter/java/z.properties | 
101
<pre><code class="ruby">org.z2env.component.type=org.z2env.java
102
</code></pre> |
103
| <HOME>/modules/greeter/java/src.impl/greetings/Main.java |
104
<pre><code class="java">
105
package greetings;
106
107
public class Main {
108
  public static void main(String[] args) {
109 8 Henning Blohm
    System.out.println("Hello!");
110 7 Henning Blohm
  }
111
}
112
</code></pre> |
113
114
That gives us the two components of module greeter. To run this on the command line, run
115
116
<pre>
117
java -DcomponentName=greeter/hello -jar z.jar
118
</pre>
119
120 1 Henning Blohm
Now, obviously this sample is not worth a modular execution environment. But even from here, you could check your module in with some Git repository that is referenced from the roots and all other users of the same repo would be able to run your component without installing anything.
121 10 Henning Blohm
122
h2. Running a Hello World Web App
123
124 11 Henning Blohm
This introduction explains how to connect a z2 core to a given Tomcat installation and how to develop a simple Web Application.
125 7 Henning Blohm
126 11 Henning Blohm
Furthermore it describes how to use the Dev Repository and the Eclipsoid plugin for the Eclipse or the IntelliJ development environment.
127 7 Henning Blohm
128 11 Henning Blohm
h3. Pre-Requisites
129
130
* We assume the Eclipse IDE.
131
* Please install the Eclipsoid Plugin from http://z2-environment.net/eclipsoid/update/site.xml
132
* We assume a development workspace in *workspace*.
133
* Have a local Tomcat (7 or higher) installation.*
134
135
h3. Steps we are going to take
136
137
# Create a module with a simple Web app
138
# Make it visible to Z2
139
# Run the Web App in a Tomcat Web Container
140
141
At first get yourself a z2env core with the *web-basic-local* or *web-basic-remote* setup. Make sure it is in your *workspace*. If you follow [[wiki#Building-z2env-core|Building the core]] this means running 
142
143
<pre>
144
ant -Doutput=workspace/z2env -Dsetup=web-basic-remote
145
</pre>
146
147
Using your IDE create a new project *hello* in *workspace* with the following structure:
148
149
150
| java/z.properties | 
151
<pre><code class="ruby">
152
org.z2env.component.type=org.z2env.java
153
java.privateReferences=\
154
	javax.servlet
155
</code></pre> |
156
| web/z.properties |
157
<pre><code class="ruby">
158
org.z2env.component.type=org.z2env.tomcat.webapp
159
webapp.path=/hello
160
</code></pre> |
161
| web/WebContent/index.jsp |
162
<pre><code class="html"><html><body>Hello! Did you know that 7*7=<%=7*7%>?</body></html></code></pre> |
163
| LOCAL | <empty file> |
164
165
So far, that's it.  We will touch on the LOCAL file later. 
166
167
When we run Z2 knowing this Web Application, it will attempt to start a Tomcat Web Container that will serve the application's content. To do that, it needs to find one. 
168
169
In order to tell Z2 where to look, you can either set an environment variable *CATALINA_HOME* (you might have already – it's the Tomcat standard) or specify an environment variable *catalina.home*. 
170
171
To be on the safe side and assuming the location is */home/me/tomcat*, we open a terminal, change into *workspace/z2env* and run
172
173
<pre>
174
java -Dcatalina.home=/home/me/tomcat -jar z.jar hello/web
175
</pre>
176
177
Note, unlike for the main program, the command line will not return. Instead you can enter „q“ to quit or „s“ to synchronize. But first let's open a browser and check out 
178
179
<pre>
180
http://localhost:8080/hello
181
</pre>
182
183
Now on to that LOCAL file. Unlike for the Hello World main program, this time it was to so-called Dev Repo that made our module available to z2. 
184
185
The dev repo is a key component to the development approach with z2. It checks for all modules that have a LOCAL file and that are stored some levels deep, relative to the parent folder of the z2 home (by default), which not so coincidentally is our workspace.
186
187
Try this: 
188
189
# Remove LOCAL
190
# Enter „s“ for synchronization. 
191
# Check the URL above (should say „not found“)
192
# Create a LOCAL file again
193
# Synchronize
194
# Check again.
195
196
Similarly, from now on, changes made to the hello module will be picked up, whenever you synchronize.
197 1 Henning Blohm
198
h2. Developing with Eclipsoid
199
200 15 Henning Blohm
Add some real code for the web app, resolve classpath in IDE with Eclipsoid.
201
(NOTE: 
202
* Eclipsoid templates have *com.zfabrik*
203
* Server port for Eclipsoid is now 8081
204
)
205 12 Henning Blohm
206 1 Henning Blohm
TBD
207 12 Henning Blohm
208
h2. Multi-Module Development
209
210
TBD
211
212
h2. Going System-Centric
213
214
TBD
215
216
Getting more real by adding a remote repo as system repo.
217
218
Develop by checking out modules and using the Dev Repo.
219
220 3 Henning Blohm
221
h2. Understanding the <HOME>
222
223
We call an installation of a z2env core a *<home>*. The file structure of the *<home>* consists of few but important locations:
224
225
| z.jar | The actual core implementation. This is precompiled.|
226
| boot/ | A component repository adding to the core and provides the most basic capabilities such as compiling Java code and running a main program. |
227
| roots/ | A file system component repository that is always registered by the core. This is typically filled with other repository components linking to remote or local component repositories. |
228
| modules/ | A file system repository declared under roots/ that is useful to locally augment a core installation.|
229 1 Henning Blohm
230
We use the modules repository for example for command line experiments and simple hacks. It is not as useful for regular development operations as is the dev repo.
231 5 Henning Blohm
232
h2. Understanding Z2
233
234
Most of the concepts that make up z2 can be derived from the desire to efficiently develop standard Java Web Applications that are defined in a central system definition. Add to that the wish to avoid all that build complexity and the desire for a practically usable modularization approach.
235
236
Once you loose the ability to tweak some build script or configuration to describe how to package a Web app or some libraries, you need some structural hint and simple declarations providing sufficient information.
237
238
Secondy, assuming you want to apply changes at runtime, you need some way of determining what to unload at runtime, given some changed file. Again: Structural information needs to present that maps to runtime state. 
239
240
Finally, as we want some support for modular application development anyway, why not make modules our essential structure. As we have not only code but also Web Applications, Data Sources,  Background Jobs and much more to consider, we add components with type into the mix. Voila.
241
242
*Component Repositories* provides modules and components to z2. A component is prefixed by the module name:
243
244
<pre>
245
<global component name> = <module name>/<local component name>
246
</pre>
247
248
In fact, the typical component repository has a file system style structure that is made up exactly like that. 
249
250
Structure from repo root:
251
252
| /<module>/<cmp>.properties | A component <cmp> in module <module> that has no resources on its own.|
253
| /<module>/<cmp>/z.properties | A component <cmp> in module <module> that may have additional resources on its own.|
254
255
Note that some components, like Web applications and typically Java components have file resources, such as HTML files or Java source code files, while other components, such as main program declarations or data source declarations, so not.
256
257
There are some conventions around this naming scheme. In particular, by convention, whenever a component requires Java implementation, z2 will first look for a component named *java* of the same module. As for example in the Hello World example.
258
259
To give you an idea what this model translates to at runtime consider this: At runtime, the static component is turned into a Resource instance by a component type implementation (that, in fact, is provided by another, built-in component type). 
260
261
!uml1.png!
262
263
Dependencies, for example those between Java components, translate into dependencies between resources that are observed during invalidation of resources. This introduces invalidation and synchronization.
264
265
A crucial concept of z2 is that of a synchronization. 
266
267
For fast development roundtrips and in some cases for general configuration updates, it is desirable to not require a complete restart of a Java Virtual Machine process but rather just to change runtime state accordingly. 
268
269
In z2 a synchronization describes the following process:
270
271
# Check for changes in component repositories
272
# Based on changes found, identify components affected and invalidate associated runtime resources incl. dependent resources.
273
# Try to attain target states
274
275 1 Henning Blohm
That is, whenever you do a change and trigger a synchronization from your IDE, this is exactly what happens: Identify what needs to be thrown away, make sure to remove dependent stuff as well,  bring up what needs to be running.
276 9 Henning Blohm
277
h2. The Component Model
278
279
See [[z2-environment:Z2_Modules_intro]]
280
281
h2. Java Components
282
283
See [[z2-environment:Z2_Java_components_intro]]