Project

General

Profile

Getting Started » History » Version 23

Henning Blohm, 02.03.2015 09:50

1 3 Henning Blohm
h1. Getting Started with org.z2env
2 1 Henning Blohm
3
See also [[FAQ]]
4
5
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. 
6
7 17 Henning Blohm
Check out [[Getting Started#Understanding-Z2|Understanding Z2]] for that.
8 1 Henning Blohm
9
It is simplest to start by running a simple Java main program in z2 or a simple Web App. 
10
11
Follow this trail:
12
13
* [[Getting Started#Building-z2env-core|Building the core]]
14
* [[Getting Started#Running-a-Hello-World-main-program|Running a Hello World main program]]
15
* [[Getting Started#Running-a-Hello-World-Web-App|Running a Hello World Web App]]
16
* [[Getting Started#Developing-with-Eclipse-or-IntelliJ|Developing with Eclipse or IntelliJ]]
17
* [[Getting Started#Going-Multi-Module|Going Multi Module]]
18 14 Henning Blohm
* [[Getting Started#Going-System-Centric|Going System Centric]]
19 18 Henning Blohm
* [[Getting Started#Understanding-the-<HOME>|Understanding the <HOME>]]
20
* [[Getting Started#Understanding-Z2|Understanding Z2]]
21 1 Henning Blohm
22 9 Henning Blohm
---
23 1 Henning Blohm
24
h2. Building z2env-core
25
26
(For now, we need to build the core).
27
28 4 Henning Blohm
{{collapse
29 1 Henning Blohm
h3. Pre-requisites
30
31
* You need Git installed
32
* You need a JDK, at least version 7
33
* You need the ANT build tool
34
35
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 20 Henning Blohm
Change into *z2env.core/org.z2env.core.main* and run 
42 1 Henning Blohm
43
<pre>
44
ant -Doutput=<z2home> -Dsetup=<setup> 
45
</pre>
46
47
where <z2home> is where you want to install z2 (the *z2 home* that is) and <setup> is a choice of pre-configured content, actually component repositories.
48
49 19 Henning Blohm
If you omit *output* it will default to *gen/dist*. If you omit *setup*, no content will be pre-configured. 
50 1 Henning Blohm
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=../../z2env 
59
</pre>
60
61 23 Henning Blohm
To install/update a web-basic setup (with tomcat and eclipsoid support) that has all addons local (i.e. no further remote synchronization) run:
62 1 Henning Blohm
63
<pre>
64 23 Henning Blohm
ant -Doutput=../../z2env -Dsetup=web-basic-local
65
</pre>
66
67
If you want your installation to update itself with the latest addon changes, run 
68
69
<pre>
70 1 Henning Blohm
ant -Doutput=../../z2env -Dsetup=web-basic-remote
71
</pre>
72 19 Henning Blohm
73 23 Henning Blohm
Both will be fine for this tutorial.
74 1 Henning Blohm
75
Check out [[wiki#Understanding-the-ltHOMEgt|Understanding the <HOME>]] to learn more about the generated structure.
76
77 2 Henning Blohm
h4. Summary
78 1 Henning Blohm
79 2 Henning Blohm
* At any time you can update a z2 core installation by running the core build and using the *output* property to point to your installation
80
* Using the *setup* property you can choose between completely local setups (no remote access required - no automatic synchronization from remote either) or mostly remote setups (all except the core will be synchronized from remote repositories). 
81
82 4 Henning Blohm
}}
83
84 9 Henning Blohm
85
---
86
87 1 Henning Blohm
h2. Running a Hello World main program
88
89 5 Henning Blohm
In this section we will let z2 do what it is actually made for: Run some Java program in a modular environment without build and deploy.
90
91 4 Henning Blohm
{{collapse
92 21 Henning Blohm
For now, we will assume you have a z2 core installed in <HOME>. If you built the core as outlined above than <HOME> is the folder *z2env* next to your core clone.
93
94
In its purest form, all the core can actually execute is simple Java main programs. 
95 1 Henning Blohm
96
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 
97
98
<pre>
99
greeter/hello
100
</pre>
101
102
Finally, as this component actually has implementation code, we need to declare a Java component. By convention this is 
103
104
<pre>
105
greeter/java
106
</pre>
107
108
Now, after installing in <HOME> the place to simply drop a module is under <HOME>/modules. You might need to create that folder.
109
110
All in all, here is the complete structure to create:
111
112
| <HOME>/modules/greeter/hello.properties | 
113
<pre><code class="ruby">org.z2env.component.type=org.z2env.main
114
component.className=greetings.Main
115
</code></pre> |
116
| <HOME>/modules/greeter/java/z.properties | 
117
<pre><code class="ruby">org.z2env.component.type=org.z2env.java
118
</code></pre> |
119
| <HOME>/modules/greeter/java/src.impl/greetings/Main.java |
120
<pre><code class="java">
121
package greetings;
122
123
public class Main {
124
  public static void main(String[] args) {
125
    System.out.println("Hello!");
126
  }
127
}
128
</code></pre> |
129
130
That gives us the two components of module greeter. To run this on the command line, run
131
132
<pre>
133
java -DcomponentName=greeter/hello -jar z.jar
134
</pre>
135 23 Henning Blohm
136
Somewhere between all the log content talking about repositories inspected by z2, you will see a humble "hello!".
137 1 Henning Blohm
138
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.
139
140 2 Henning Blohm
h4. Summary
141
142
* Running a simple program in a modular environment requires no more than declaring the modules and add some code
143
* Apart from more technical component types, at the heart of the z2 core is to run simple Java main programs
144
145 4 Henning Blohm
}}
146 2 Henning Blohm
147 9 Henning Blohm
148
---
149
150 1 Henning Blohm
h2. Running a Hello World Web App
151
152 6 Henning Blohm
Rather than just running a Main program, using the Tomcat add-on we might as well run full-featured Web applications - of course: From anywhere, without build and deploy.
153
154 4 Henning Blohm
{{collapse
155
156 1 Henning Blohm
This introduction explains how to connect a z2 core to a given Tomcat installation and how to develop a simple Web Application.
157
158
Furthermore it describes how to use the Dev Repository and the Eclipsoid plugin for the Eclipse or the IntelliJ development environment.
159
160
h3. Pre-Requisites
161
162
* We assume a development workspace in *workspace*.
163
* Have a local Tomcat (7 or higher) installation.*
164
165
h3. Steps we are going to take
166
167
# Create a module with a simple Web app
168
# Make it visible to Z2
169
# Run the Web App in a Tomcat Web Container
170
171
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 
172
173
<pre>
174
ant -Doutput=workspace/z2env -Dsetup=web-basic-remote
175
</pre>
176
177
(*Note:* If in doubt, use an absolute path for *workspace*)
178
179
Using your IDE create a new project *hello* in *workspace* with the following structure:
180
181
| java/z.properties | 
182
<pre><code class="ruby">
183
org.z2env.component.type=org.z2env.java
184
java.privateReferences=\
185
	javax.servlet
186
</code></pre> |
187
| web/z.properties |
188
<pre><code class="ruby">
189
org.z2env.component.type=org.z2env.tomcat.webapp
190
webapp.path=/hello
191
</code></pre> |
192
| web/WebContent/index.jsp |
193
<pre><code class="html"><html><body>Hello! Did you know that 7*7=<%=7*7%>?</body></html></code></pre> |
194
| LOCAL | <empty file> |
195
196
Your *workspace* folder now contains two subfolders *z2env* and *hello*.
197
198
So far, that's it.  We will touch on the LOCAL file later. 
199
200
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. 
201
202
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*. 
203
204
To be on the safe side and assuming the location is */home/me/tomcat*, we open a terminal, change into *workspace/z2env* and run
205
206
<pre>
207
java -Dcatalina.home=/home/me/tomcat -jar z.jar hello/web
208
</pre>
209
210
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 
211
212
<pre>
213
http://localhost:8080/hello
214
</pre>
215
216
*Note:* What you just created is a prototypical z2 module structure containing a Java component *java* (holding implementation) and a Web component *web*. 
217
218
Instead of creating the structure yourself, you could use the Eclipsoid plugin (introduced below) for that:
219
* In Eclipse: New / Others / new z2...., 
220
* In IntelliJ: New / Module / z2....
221
222
... but beware of the pre-generated configuration. Where it says *com.zfabrik* change to *org.z2env*.
223
224
225
*Note:* 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. 
226
227
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.
228
229
We call modules with a LOCAL file _armed_.
230
231
*Note:* By default the dev repo looks for modules beneath the parent folder of the <home> location. Use the system property *org.z2env.dev.local.workspace* to specify other locations (separated by comma) to check for modules.
232
233
234
Try this: 
235
236
# Remove LOCAL
237
# Enter „s“ for synchronization. 
238
# Check the URL above (should say „not found“)
239
# Create a LOCAL file again
240
# Synchronize
241
# Check again.
242
243
Similarly, from now on, changes made to the hello module will be picked up, whenever you synchronize.
244
245 2 Henning Blohm
h4. Summary
246
247
* Addons extend z2 with capabilities, such as a Tomcat hosted Web application (albeit running in z2's module environment)
248
* The _dev repository_ allows to flexibly define local modules. Modules can put into or out visibility by a simple LOCAL marker file.
249
250 4 Henning Blohm
}}
251
252 9 Henning Blohm
253
---
254
255 1 Henning Blohm
h2. Developing with Eclipse or IntelliJ
256
257
In this section we will add some code to the hello Web app and see how to develop using an integrated development environment like the Eclipse IDE or Jetbrains' IntelliJ IDEA.
258
259 4 Henning Blohm
{{collapse
260
261 1 Henning Blohm
h3. Pre-Requisite
262
263
* Have an Eclipse or IntelliJ installation
264
* Install the Eclipsoid plugin from http://z2-environment.net/eclipsoid/update/site.xml or by searching for "z2" in the IntelliJ Plugin Repository respectively
265
266
h3. Steps we are going to take
267
268
# Complete the development workspace setup
269
# Add a simple Controller
270
271
h4. In Eclipse
272
273
Use the workspace *workspace*. Create a Java project *hello* where we created the *hello* module. That is, we use the existing module as project content. You should now have an Eclipse development workspace that has one Java project named "hello". Right-click on the project and choose "Transform into z2 Project". A small "Z" icon should not decorate the project icon. 
274
275
Add a source folder *java/src.impl* to the project.
276
277
Try "Arm Z2 Projects" and "Disarm Z2 Projects" from the context menu. You should see a LOCAL file showing up and disappearing as well as the "Z" decoration showing a green halo and going back to normal. 
278
279
Go into Window/Preferences, pick "z2-Environment". Change the port to 8081, set the user to "z*" and the password to "z". Done.
280
281
h4. In IntelliJ
282
283
Add a source folder *java/src.impl* to the module.
284
285
Start a new Project with root folder *workspace*. Press the "Manage z2-Modules" button in the toolbar. Import the *hello* module into your IntelliJ project. Open the Settings dialog, pick "z2-Environment". Change the port to 8081, set the user to "z*" and the password to "z". Done.
286
287
h4. Independently of whether you use IntelliJ or Eclipse
288
289
Start z2 as in the previous section but make sure the development support is enabled. Use this command line:
290
291
<pre>
292
java -Dcatalina.home=/home/me/tomcat -jar z.jar org.z2env.dev.shared/ready hello/web
293
</pre>
294
295
(possibly you want to turn this into a shell script)
296
297
*Note:* The _system state_ *org.z2env.dev.shared/ready* will pull up all necessary development support components. Make sure this is part of your to-be-run list.
298
299
300
Regardless whether you are using Eclipse or IntelliJ, press the "Resolve Classpath from Z2" button in the toolbar. This will make sure that all required dependencies for Z2 modules, as far as Java code is concerned, will be resolved for your workspace. 
301
302
Now add a class *SimpleController* and change the following files:
303
304
| java/src.impl/hello/SimpleController.java | 
305
<pre><code class="java">
306
package hello;
307
308 11 Henning Blohm
import goodbye.GoodbyeService;
309
310 1 Henning Blohm
import java.io.IOException;
311
312 11 Henning Blohm
import javax.servlet.ServletException;
313
import javax.servlet.annotation.WebServlet;
314
import javax.servlet.http.HttpServlet;
315
import javax.servlet.http.HttpServletRequest;
316
import javax.servlet.http.HttpServletResponse;
317 1 Henning Blohm
318 11 Henning Blohm
import org.z2env.components.IComponentsLookup;
319
320
@WebServlet(urlPatterns="/do")
321
public class SimpleController extends HttpServlet {
322 13 Henning Blohm
    private static final long serialVersionUID = 1L;
323
324
    @Override
325
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
326
        GoodbyeService gb = IComponentsLookup.CL.lookup("goodbye/service", GoodbyeService.class);
327
        String input = req.getParameter("input");
328 1 Henning Blohm
        if (input!=null && input.trim().length()>0) {
329 11 Henning Blohm
            req.setAttribute(
330
                "output",
331 12 Henning Blohm
                "Hello "+input
332 11 Henning Blohm
            );
333
            req.setAttribute("input",input);
334 1 Henning Blohm
        }
335
        req.getRequestDispatcher("/").forward(req,resp);
336
    }
337 16 Henning Blohm
}</code></pre> |
338 1 Henning Blohm
| java/z.properties | 
339
<pre><code class="ruby">
340
org.z2env.component.type = org.z2env.java
341
342
java.privateReferences=\
343
  javax.servlet,\
344
  javax.servlet.jsp.jstl
345
</code></pre> |
346
| web/WebContent/index.jsp |
347
<pre><code class="html">
348
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core_1_1" %>
349
<html>
350
<body>
351
  <c:if test="${not empty output}">
352
    <p><c:out value="${output}"/></p>
353
  </c:if>
354
  <form method="POST" action="<c:url value='/do'/>">
355
    Input: <input type="text" name="input"><input type="submit" value="go!">
356
  </form>
357
</body>
358
</html>
359
</code></pre>|
360
361
Make sure the *hello* module is armed (right-click) by having a LOCAL file.
362
363
Now synchronize your running z2 by either:
364
365
* Pressing the "Sync with z2-Environment" button in the toolbar
366
* Pressing ALT+y in your IDE
367
* Entering "s" on the command line running z2.
368
369
Go to http://localhost:8080/hello and check it out.
370
371 2 Henning Blohm
h4. Summary
372 1 Henning Blohm
373 2 Henning Blohm
* Using IDE plugins for Eclipse or IntelliJ you can conveniently develop for Z2.
374
* Regardless of the component types in use, all class path considerations will be resolved from Z2 and you will never need to change IDE configuration.
375
* Using the interplay of IDE plugin and the dev repository (see also [[FAQ#Development]]) synchronization from the IDE and overlay of modules with local development versions is simple and fast. 
376
377 4 Henning Blohm
}}
378
379 9 Henning Blohm
380
---
381
382 1 Henning Blohm
h2. Going Multi-Module
383
384
In this section we will extend the previous work by a simple service module. 
385
386 4 Henning Blohm
{{collapse
387 1 Henning Blohm
h3. Pre-Requisites
388
389
# Have all the results from the previous section ready.
390
# Start IDE and z2 as above.
391
392
393
h3. Steps we are going to take
394
395
# add a new module with a service API
396
# reference the module API from the *hello* module and invoke the service.
397
398
399
In your workspace, use Eclipsoid to create a new z2 Java module *goodbye*. Open *java/z.properties* and change all *com.zfabrik.* prefixes to *org.z2env*. Essentially the file only needs the line
400
401
<pre><code class="ruby">
402
org.z2env.component.type=org.z2env.java
403
</code></pre>
404
405
In our API we will only expose an interface and rather leave the implementation hidden in the implementation parts of the module. We do that, as we prefer a strong separation of API and implementation. This is not at all required but a conscious design choice. 
406
407
408
| java/src.api/goodbye/GoodbyeService.java | 
409
<pre><code class="java">
410
package goodbye;
411
412
public interface GoodbyeService {
413
414
	String sayGoodbye(String in);
415
	
416
}
417
418
</code></pre> |
419
| java/src.impl/goodbye/GoodbyeServiceImpl.java | 
420
<pre><code class="java">
421
package goodbye;
422
423
public class GoodbyeServiceImpl implements GoodbyeService {
424
425
	@Override
426
	public String sayGoodbye(String in) {
427
		return "Goodbye "+in+"!";
428
	}
429
430
}
431
</code></pre> |
432 10 Henning Blohm
| service.properties | 
433 1 Henning Blohm
<pre><code class="ruby">
434
org.z2env.component.type=org.z2env.any
435
component.className=goodbye.GoodbyeServiceImpl
436
</code></pre> |
437
| java/z.properties | 
438
<pre><code class="ruby">
439
org.z2env.component.type=org.z2env.java
440
</code></pre> |
441
442
In effect we created the following:
443
444
* A module *goodbye* that has 
445
* A Java component with API and Implementation source code
446
* An _any_ component *goodbye/service* that manages the service implementation (as we will see below)
447
448
Back in the *hello* module, we want to use the _goodbye service_. We apply the following changes:
449
450
| java/z.properties | 
451
<pre><code class="ruby">
452
org.z2env.component.type=org.z2env.java
453
454
java.privateReferences=\
455
    javax.servlet,\
456
    javax.servlet.jsp.jstl,\
457
    goodbye
458
</code></pre> |
459
| java/src.impl/hello/SimpleController.java | 
460
<pre><code class="java">
461
package hello;
462
463
import goodbye.GoodbyeService;
464
465
import java.io.IOException;
466
467
import javax.servlet.ServletException;
468 13 Henning Blohm
import javax.servlet.annotation.WebServlet;
469 1 Henning Blohm
import javax.servlet.http.HttpServlet;
470
import javax.servlet.http.HttpServletRequest;
471
import javax.servlet.http.HttpServletResponse;
472
473
import org.z2env.components.IComponentsLookup;
474
475 13 Henning Blohm
@WebServlet(urlPatterns="/do")
476 1 Henning Blohm
public class SimpleController extends HttpServlet {
477 13 Henning Blohm
    private static final long serialVersionUID = 1L;
478 1 Henning Blohm
479
    @Override
480
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
481 13 Henning Blohm
        GoodbyeService gb = IComponentsLookup.CL.lookup("goodbye/service", GoodbyeService.class);
482 1 Henning Blohm
        String input = req.getParameter("input");
483
        if (input!=null && input.trim().length()>0) {
484
            req.setAttribute(
485 13 Henning Blohm
                "output",
486
                gb.sayGoodbye(input)
487
            );
488
            req.setAttribute("input",input);
489 1 Henning Blohm
        }
490
        req.getRequestDispatcher("/").forward(req,resp);
491
    }
492
}
493
</code></pre> |
494
495
After you have changed the Java references in *java/z.properties* you might want to press Alt-R or the "Resolve Classpath from Z2" button in the toolbar to have the IDE resolve the dependency for the *goodbye* module and so that
496
your IDE will not complain about using the *GoodbyeService* interface.
497
498
Now synchronize your running z2 by either:
499
500
* Pressing the "Sync with z2-Environment" button in the toolbar
501
* Pressing ALT+y in your IDE
502
* Entering "s" on the command line running z2.
503
504
Go to http://localhost:8080/hello and check it out.
505
506
h3. Discussion
507
508
What you just implemented is a programmatic component lookup. The first time <code>IComponentsLookup.CL.lookup("goodbye/service", GoodbyeService.class)</code> was invoked, z2 searched for a factory for *org.z2env.any* components. This specific factory simply created a singleton instance of the Goodbye Service and checked whether the requested interface is implemented. As that held, it returned the actual instance.
509
510
In later sections (for now check out [[z2-environment:How_to_Spring]]) we will explain how to that extends to the Spring Framework and Dependency Injection in general.
511 2 Henning Blohm
512
h4. Summary
513
514
* Being a modular runtime environment, Z2 offers an effective yet simple Java modularization approach
515
* The module concept of Z2 goes beyond code considerations and includes arbitrary component types such as Web applications
516 1 Henning Blohm
517
Feel free to apply changes to the Goodbye Service implementation class and have them made effective by synchronizing Z2.
518 4 Henning Blohm
519
}}
520 8 Henning Blohm
521 1 Henning Blohm
522 9 Henning Blohm
---
523
524 1 Henning Blohm
h2. Going System-Centric
525 2 Henning Blohm
526
In this section we show how to turn your z2 installation into a mere execution node of a system (which is what it really should be). That is, in team development situations for systems of non-trivial size of distribution requirements, it is crucial to be integrated with a common source code level. 
527 1 Henning Blohm
528 4 Henning Blohm
{{collapse
529
530 2 Henning Blohm
Using remote repositories in combination with the dev repository, z2 offers just that: Integration for all but those pieces you do actually need isolation from changes.
531
532
Using z2's synchronization approach rolling out changes to remote installation and scale-outs become a non-issue.
533 8 Henning Blohm
534
h3. Pre-Requisites
535
536
# Have the multi-module setup from the previous section at hand
537
# Start IDE and z2 as above.
538
539 2 Henning Blohm
540
h3. Steps we are going to take
541
542
# check our modules in with some new Git repository
543
# add a Git-based component repository component 
544
# develop with partial overlays
545
546
547 1 Henning Blohm
548 4 Henning Blohm
}}
549 1 Henning Blohm
550 9 Henning Blohm
551
552
---
553 1 Henning Blohm
554
h2. Understanding the <HOME>
555
556 4 Henning Blohm
We call an installation of a z2env core a *<home>*. The file structure of the *<home>* consists of few but important locations.
557 1 Henning Blohm
558 4 Henning Blohm
{{collapse
559 1 Henning Blohm
h3. Layout
560
561
| z.jar | The actual core implementation. This is precompiled.|
562
| boot/ | A component repository adding to the core and provides the most basic capabilities such as compiling Java code and running a main program. |
563
| 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. |
564
| modules/ | A file system repository declared under roots/ that is useful to locally augment a core installation.|
565
566
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.
567
568 4 Henning Blohm
569 1 Henning Blohm
h3. Folders and Properties
570
571
When running z2 from the command line, some logic is applied to derive where stuff is and some defaults apply:
572
573
|_. What |_. System property |_. Defaults |
574
| Z2 home - the installation location | org.z2env.home | If no system property is set, the environment variable Z2_HOME will be checked. If that is not set, the z2 home location will be derived from the location of the z.jar file |
575
| Dev Repo workspaces - where the Dev Repo checks for local modules | org.z2env.dev.local.workspaces | Defaults to ${z2.home}/.. assuming modules will be next to the home or one level deeper |
576
577 4 Henning Blohm
See also [[Core Layout]]
578 1 Henning Blohm
579
}}
580 4 Henning Blohm
581 17 Henning Blohm
---
582 18 Henning Blohm
583 1 Henning Blohm
h2. Understanding Z2
584
585
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.
586
587 4 Henning Blohm
{{collapse
588 1 Henning Blohm
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.
589
590
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. 
591
592
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.
593
594
*Component Repositories* provides modules and components to z2. A component is prefixed by the module name:
595
596
<pre>
597
<global component name> = <module name>/<local component name>
598
</pre>
599
600
In fact, the typical component repository has a file system style structure that is made up exactly like that. 
601
602
Structure from repo root:
603
604
| /<module>/<cmp>.properties | A component <cmp> in module <module> that has no resources on its own.|
605
| /<module>/<cmp>/z.properties | A component <cmp> in module <module> that may have additional resources on its own.|
606
607
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.
608
609
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.
610
611
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). 
612
613
!uml1.png!
614
615
Dependencies, for example those between Java components, translate into dependencies between resources that are observed during invalidation of resources. This introduces invalidation and synchronization.
616
617
h3. A crucial concept of z2 is that of a synchronization. 
618
619
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. 
620
621
In z2 a synchronization describes the following process:
622
623
# Check for changes in component repositories
624
# Based on changes found, identify components affected and invalidate associated runtime resources incl. dependent resources.
625
# Try to attain target states
626
627
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.
628
629
h3. A second crucial concept of z2 is that of *System Centric Development*
630
631
When working on a software system with many access points and high re-use on a service level, as is typical for business systems, staying quick integration with a team's changes is key. Component repositories can be fed from remotely accessible version control systems such as Subversion and Git. When connecting to a central, team-shared repository, every synchronization will make sure that you are up-to-date with the real source of truth. 
632
633
Using the dev repo, you can still isolate yourself from changes on part of the system that you are actively working on. After your modifications are completed, rebased, and locally tested, getting a clean and consistent state is just one synchronization away.
634
635
h3. The third and final concept is that of a compile-free environment
636
637
It is within the nature of the synchronization concept, that anything required to happen to have your software available for execution must have happened after synchronization completed. Most preparation steps are executed at first use. This includes the compilation of Java code. Z2 uses the Eclipse Java Compiler for that purpose.
638
639
h2. The Component Model
640
641
See [[z2-environment:Z2_Modules_intro]]
642
643
h2. Java Components
644
645
See [[z2-environment:Z2_Java_components_intro]]
646 4 Henning Blohm
647
}}