Project

General

Profile

Wiki » History » Version 6

Henning Blohm, 22.01.2015 16:38

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 3 Henning Blohm
* The <z2 home> layout is completely new.
11
* The essential component types that can be _invoked_ from the core is *system state* and *main program*.
12 2 Henning Blohm
* While Jetty is still contained to support Eclipsoid and z2Unit, we support a pre-installed Tomcat as application container.
13 1 Henning Blohm
* The core is lighter and more dedicated. 
14 3 Henning Blohm
* No worker suppport without a corresponding add-on.
15 2 Henning Blohm
* There will be substantially less application support like a built-in JTA implementation but we will rather demonstrate how to use third-party tools.
16 1 Henning Blohm
17 2 Henning Blohm
h1. Draft Documentation
18 1 Henning Blohm
19 2 Henning Blohm
h2. Getting Started
20 1 Henning Blohm
21 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. 
22 1 Henning Blohm
23 6 Henning Blohm
Check out [[wiki#Understanding-Z2|understanding-z2]] for that.
24 1 Henning Blohm
25 2 Henning Blohm
It is simplest to start by running a simple Java main program in z2 or a simple Web App. 
26 1 Henning Blohm
27 2 Henning Blohm
Follow this trail:
28 1 Henning Blohm
29 4 Henning Blohm
* [[wiki#Building-z2env-core|Building the core]]
30 3 Henning Blohm
* [[wiki#running-a-hello-world-main-program|Running a Hello World main program]]
31
* [[wiki#running-a-hello-world-web-app|Running a Hello World Web App]]
32 1 Henning Blohm
33 3 Henning Blohm
h2. Building z2env-core
34 1 Henning Blohm
35 3 Henning Blohm
First clone http://git.z2-environment.net/z2env.core
36
37
<pre>
38
git clone http://git.z2-environment.net/z2env.core
39
</pre>
40
41
Switch into *org.z2env.core.main* and run 
42
43
<pre>
44 5 Henning Blohm
ant -Doutput=<location of z2 home> -Dsetup=<preconfigured roots> 
45 3 Henning Blohm
</pre>
46
47 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.
48 3 Henning Blohm
49
If you omit *output* it will default to *gen/dist*. If you omit *setup*, no content will be pre-configured will be modified. 
50
51
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).
52
53
In general this build always updates only boot, z.jar, roots. It will not remove anything.
54
55
Example to install/update a core only into ../../z2env:
56
57
<pre>
58
ant -Doutput=here 
59
</pre>
60
61
To install/update a web-basic setup (with tomcat and eclipsoid support) with updates from remote repos:
62
63
<pre>
64
ant -Doutput=../../z2env -Dsetup=web-basic-remote
65
</pre>
66
67
h2. Understanding the <HOME>
68
69
We call an installation of a z2env core a *<home>*. The file structure of the *<home>* consists of few but important locations:
70
71
| z.jar | The actual core implementation. This is precompiled.|
72
| boot/ | A component repository adding to the core and provides the most basic capabilities such as compiling Java code and running a main program. |
73
| 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. |
74
| modules/ | A file system repository declared under roots/ that is useful to locally augment a core installation.|
75 1 Henning Blohm
76
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.
77 5 Henning Blohm
78
h2. Understanding Z2
79
80
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.
81
82
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.
83
84
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. 
85
86
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.
87
88
*Component Repositories* provides modules and components to z2. A component is prefixed by the module name:
89
90
<pre>
91
<global component name> = <module name>/<local component name>
92
</pre>
93
94
In fact, the typical component repository has a file system style structure that is made up exactly like that. 
95
96
Structure from repo root:
97
98
| /<module>/<cmp>.properties | A component <cmp> in module <module> that has no resources on its own.|
99
| /<module>/<cmp>/z.properties | A component <cmp> in module <module> that may have additional resources on its own.|
100
101
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.
102
103
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.
104
105
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). 
106
107
!uml1.png!
108
109
Dependencies, for example those between Java components, translate into dependencies between resources that are observed during invalidation of resources. This introduces invalidation and synchronization.
110
111
A crucial concept of z2 is that of a synchronization. 
112
113
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. 
114
115
In z2 a synchronization describes the following process:
116
117
# Check for changes in component repositories
118
# Based on changes found, identify components affected and invalidate associated runtime resources incl. dependent resources.
119
# Try to attain target states
120
121
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.