Project

General

Profile

V29-Reference » History » Version 8

Henning Blohm, 19.08.2021 23:15

1 7
p=. Please find the detailed documentation of v2.9 below.
2
3
p=. A PDF version can be downloaded here: attachments:z2_env_fulldoc_2_9.pdf.
4
5
6
7
8
9
p{ text-align:center; font-size:large; }. System Development
10
11
12
p{ text-align:center; font-size:large; }. for Java 
13
14
15
p{ text-align:center; font-size:large; }. with the z2-Environment
16
17
18
19
20
21
p=. Version 2.9
22
23
24
25
26
p=. Last updated on:
27
28
29
p=. August 19, 2021
30
31
32
1.  [[#Introduction|Introduction]] 
33
1.1.  [[#What is the z2-Environment|What is the z2-Environment]] 
34
1.2.  [[#Online resources|Online resources]] 
35
2.  [[#Installing and Understanding a Z2 Home|Installing and Understanding a Z2 Home]] 
36
2.1.  [[#The z2-base Distribution|The z2-base Distribution]] 
37
2.2.  [[#Home install in 2 minutes|Home install in 2 minutes]] 
38
2.3.  [[#Folder Structure of a Z2 Home|Folder Structure of a Z2 Home]] 
39
2.4.  [[#Starting and synchronizing|Starting and synchronizing]] 
40
2.5.  [[#Important System Properties|Important System Properties]] 
41
2.6.  [[#The Base Repository|The Base Repository]] 
42
2.7.  [[#Worker Processes and Home Layouts|Worker Processes and Home Layouts]] 
43
3.  [[#Anatomy|Anatomy]] 
44
3.1.  [[#Working on-demand|Working on-demand]] 
45
3.1.1.  [[#The Resource Management System|The Resource Management System]] 
46
3.1.2.  [[#The z2 Command Line, the Embedded Runtime and the Main Runner|The z2 Command Line, the Embedded Runtime and the Main Runner]] 
47
3.2.  [[#Components and Component Repositories|Components and Component Repositories]] 
48
3.2.1.  [[#Synchronization with updates|Synchronization with updates]] 
49
3.2.2.  [[#File system support|File system support]] 
50
3.2.3.  [[#Subversion support|Subversion support]] 
51
3.2.4.  [[#Git support|Git support]] 
52
3.2.5.  [[#Maven Repository Support|Maven Repository Support]] 
53
3.2.6.  [[#Component Types and Component Factories|Component Types and Component Factories]] 
54
3.2.7.  [[#Dynamic Component Properties|Dynamic Component Properties]] 
55
3.2.8.  [[#Using Dynamic Property Expressions with JEXL3|Using Dynamic Property Expressions with JEXL3]] 
56
3.2.9.  [[#Java Naming and Directory Interface (JNDI) support|Java Naming and Directory Interface (JNDI) support]] 
57
3.2.10.  [[#Link Components and Component Linking|Link Components and Component Linking]] 
58
3.3.  [[#Unit of Work and transaction management|Unit of Work and transaction management]] 
59
4.  [[#Constructing a Z2 system|Constructing a Z2 system]] 
60
4.1.  [[#Add-ons|Add-ons]] 
61
5.  [[#Developing with the z2-Environment|Developing with the z2-Environment]] 
62
5.1.  [[#A note on what JDK to use|A note on what JDK to use]] 
63
5.2.  [[#Workspace development using the Dev Repository |Workspace development using the Dev Repository]] 
64
5.2.1.  [[#Recommended folder structure |Recommended folder structure]] 
65
5.3.  [[#The Eclipsoid Plug-in|The Eclipsoid Plug-in]] 
66
5.4.  [[#Using the Offline Mode|Using the Offline Mode]] 
67
5.4.1.  [[#How the offline mode is used. |How the offline mode is used.]] 
68
5.4.2.  [[#Enabling Offline mode at start time |Enabling Offline mode at start time]] 
69
5.4.3.  [[#Toggling Offline Mode during Development |Toggling Offline Mode during Development]] 
70
5.5.  [[#In-container unit testing using Z2 Jupiter|In-container unit testing using Z2 Jupiter]] 
71
5.6.  [[#Retrieving jars from Z2|Retrieving jars from Z2]] 
72
6.  [[#Managing z2|Managing z2]] 
73
6.1.  [[#The Basic Admin Interface|The Basic Admin Interface]] 
74
6.2.  [[#The JMX Remoting Command Line Interface|The JMX Remoting Command Line Interface]] 
75
7.  [[#Enhanced Basis Features|Enhanced Basis Features]] 
76
7.1.  [[#The Binary Hub Component Repository|The Binary Hub Component Repository]] 
77
7.2.  [[#The Gateway for Zero-Downtime-Upgrades |The Gateway for Zero-Downtime-Upgrades]] 
78
8.  [[#Component type reference|Component type reference]] 
79
8.1.  [[#Core component properties|Core component properties]] 
80
8.2.  [[#“Any” components (core)|“Any” components (core)]] 
81
8.3.  [[#Component Factories (core)|Component Factories (core)]] 
82
8.4.  [[#Data Source components (z2-base)|Data Source components (z2-base)]] 
83
8.4.1.  [[#Data Source Specific Configuration|Data Source Specific Configuration]] 
84
8.4.2.  [[#Data Source Types|Data Source Types]] 
85
8.5.  [[#File system component repositories (core)|File system component repositories (core)]] 
86
8.6.  [[#GIT component repositories (core)|GIT component repositories (core)]] 
87
8.7.  [[#Java components (core)|Java components (core)]] 
88
8.7.1.  [[#Classloaders|Classloaders]] 
89
8.7.2.  [[#Includes|Includes]] 
90
8.8.  [[#JUL configurations (z2-base)|JUL configurations (z2-base)]] 
91
8.9.  [[#Link Components|Link Components]] 
92
8.10.  [[#Log4J configurations (z2-base)|Log4J configurations (z2-base)]] 
93
8.11.  [[#Main Program Components (core)|Main Program Components (core)]] 
94
8.12.  [[#Maven component repositories (z2-base)|Maven component repositories (z2-base)]] 
95
8.13.  [[#Maven component repository fragments (z2-base)|Maven component repository fragments (z2-base)]] 
96
8.14.  [[#Subversion component repositories (core)|Subversion component repositories (core)]] 
97
8.15.  [[#System States (core)|System States (core)]] 
98
8.16.  [[#Web applications (z2-base)|Web applications (z2-base)]] 
99
8.17.  [[#Web servers (z2-base)|Web servers (z2-base)]] 
100
8.18.  [[#Worker Processes (z2-base)|Worker Processes (z2-base)]] 
101
8.18.1.  [[#System Property Propagation from Home to Worker Process|System Property Propagation from Home to Worker Process]] 
102
8.18.2.  [[#Special considerations when specifying VM options using blanks and quotes|Special considerations when specifying VM options using blanks and quotes]] 
103
9.  [[#Securing z2 for Production Use|Securing z2 for Production Use]] 
104
9.1.  [[#Securing Access to Ports|Securing Access to Ports]] 
105
9.2.  [[#Non-Localhost-Whitelisting|Non-Localhost-Whitelisting]] 
106
107
h2. Introduction
108
109
110
p. Developing applications for the Java platform typically involves a number of steps that are needed to be performed before execution. At the least it is required to run a Java compiler that turns Java source code into executable byte code.
111
112
113
p. Coding environments like the Eclipse or the IntelliJ Integrated Development Environments do a great job of hiding these operations to the user for simple applications. When applications become more complex though, modularization needs and team development approaches ask for more sophisticated tools to make sure that growing system complexity can be managed.
114
115
116
p. The traditional development approach for Java applications resembles that of Desktop applications. Apart from compiling source code into an executable representation, execution of additional operations, the _build process_, needs to be completed before execution. This includes resolution of module dependencies and packaging of generated as well as retrieved artifacts into some _*deployable*_ file format that will be installed (_deployed_) in some execution environment. For Java applications the latter is either a standalone Java Virtual Machine (JVM) or an application server.
117
118
119
p. For Desktop applications that can assume very little about their execution environment it is a necessity to be self-contained and easily distributable in some file format.
120
121
122
p. The situation for Intranet and Internet applications is different. A major part of the life cycle of a business application installation consists of change: ongoing development, customization, extension, and repair. 
123
124
125
p. All but the most trivial business applications are a composition of subsystems that make strong assumptions on the presence and behavior of other subsystems – all together forming a software system that offers a wide range of access methods, performs recurring background jobs, integrates with other systems in whole landscape of systems, and operates over a shared and evolving data asset.
126
127
128
p. Platforms that are heavily geared towards development and operation of business applications, such as SAP's ABAP environment or Oracle's PL/SQL platform therefore take a different view. Instead of mimicking the concept of a most generic operating system that runs largely independent, locally _installed _binary applications, the focus of these environments is to perform the functions of a large highly interconnected software system at scale, agnostic to the single machine, with as little local configuration as possible. Instead of being the end of a tool chain that is a mere executor of binary code in some undecipherable interplay, a centrally defined, customizable and extensible system definition in the form of source code and configuration that is executable without build process complexities by arbitrarily many machine nodes running the platform is crucial to managing software life cycle complexity at scale. 
129
130
131
p. The z2-Environment brings these qualities to the world of Java applications. We call it the _system-centric _approach.
132
133
134
h3. What is the z2-Environment
135
136
137
p. Practically speaking the z2-Environment is a Java-based runtime environment that knows how to update itself from source code and configurations stored in repositories of various technologies, including source control systems like Git and Subversion or just a plain old file system.
138
139
140
p. Z2 defines an extensible component and modularization model that, based on few basic paradigms and interfaces, allows to construct full-blown modular application systems.
141
142
143
p. The z2-Environment can be used to build Java EE Web applications as well as standalone Java applications without restricting the use of third-party libraries and popular frameworks like the Spring Framework, Hibernate/JPA, and many more.
144
145
146
p. Z2 is strictly implemented on Java:
147
148
* Versions before 2.4 require Java 6 and support Java 6 and Java 7  language levels. 
149
* As of version 2.4, Z2 requires Java 8,
150
* As of version 2.6, Z2 requires Java 9 and supports Java 9 and Java 10,
151
* As of version 2.7, Z2 requires Java 9 and supports Java 9, Java 10, and Java 11.
152
* As of version 2.8, Z2 requires Java 9 and supports Java 9, and higher up to Java 13.
153
* As of version 2.9, Z2 requires Java 11 and supports Java 15 and higher.
154
155
p. See also [[#A note on what JDK to use|A note on what JDK to use]]  for more details.
156
157
158
h3. Online resources
159
160
161
p. Z2 can be installed and tried out in a matter of minutes. There are various how-tos and samples available that explain and demonstrate the use of Z2. 
162
163
164
p. This documentation and high-level information can be found in the Wiki at 
165
166
167
p. "https://redmine.z2-environment.net/projects/z2-environment/wiki":https://redmine.z2-environment.net/projects/z2-environment/wiki 
168
169
170
h2. Installing and Understanding a Z2 Home
171
172
173
p. In order to access component repositories and to implement its component and modularization model at runtime, the elementary capabilities of Z2 need to be installed as a normal Java program in binary form. The most fundamental features of Z2 are implemented in the _z2 core_. It's source code and its simple build script, including instructions, can be found on the Wiki site. We call a local installation of a z2-core a _z2 Home_.
174
175
176
p. In its basic form, the z2 core knows little more than running Java main programs from source in a modular context. In order to turn a z2 home into a node of a capable system we need to connect it to repositories defining further component types, libraries, and applications.
177
178
179
p. This is done by declaring component repository components as will be explained below. Choosing remote repositories will give you a system that is centrally defined and scales easily with consistent updates. 
180
181
182
p. Choosing only local repositories will leads to system that can be maintained and distributed like a Scripting language application, albeit being implemented using Java.
183
184
185
h3. The z2-base Distribution
186
187
188
p. Starting with version 2.6, when you download z2 for installation, you are encouraged to download the *z2-base distribution* from the Web site. The z2-base distribution does not only contain the z2 core but also a locally configured *z2-base.base* repository in the *base* folder (see below), providing the Jetty Web Container and other components that are useful for most anything you might want to do, without requiring remote access to the z2-base Git repositories. 
189
190
191
p. The alternative is to use the *z2-core distribution* that only contains the z2-core binaries and has a remote-configured z2-base repository. For larger applications where the need for z2 home updates should be minimized this would be the right choice. 
192
193
194
p. To sum it up:
195
196
| Distribution| Contains| When to use |
197
| z2-base| The z2 core binaries and a locally configured z2-base.base repository. | Getting started. Needs no remote access to anywhere and can be easily extended using local modules (see [[#Developing with the z2-Environment|#develop]] ). |
198
| z2-core| The z2 core binaries and a remote configured z2-base.base repository. | Updating or setting up a distributed system that is configured and extended using remote repositories. |
199
200
201
202
h3. Home install in 2 minutes
203
204
205
p. Generally you install a z2 Home by downloading and unpacking a z2 base distribution from the Web site. Distribution ZIP an TAR archives are named including the distribution base name (e.g. z2-base), the version branch, as well as the actual build time stamp.
206
207
208
p. For example, from a linux command line prompt you might run:
209
210
211
<pre><code class="bash">mkdir install
212
cd install
213
wget http://download.z2-environment.net/z2/z2-base-v2.9.tar.gz
214
tar xf z2-base-v2.9.tar.gz
215
z2-base.core/bin/gui.sh</code></pre>
216
217
218
p. installing a z2 Home at z2-base.core in the install folder and starting the development graphical user interface. 
219
220
221
h3. Folder Structure of a Z2 Home
222
223
224
p. Typically a home installation folder has the following file and folder structure:
225
226
227
**bin**
228
229
230
p. This folder holds the actual z2 start code and shell scripts. This is from where you run z2.
231
232
233
234
**local**
235
236
237
p. This folder holds all core modules that have been pre-compiled as part of the z2-core build. Normally you do not need to touch anything in here.
238
239
240
241
**base**
242
243
244
p. When using the z2-base distribution this folder holds the complete z2-base.base modules. The z2-base.base repository is the application foundation on z2 and holds the Jetty web container and some fundamental libraries and applications.
245
246
247
248
**config**
249
250
251
p. The config folder is another z2 component repository meant to be used to define modules that tweak or add configuration to z2, in particular other sources of modules. By default there is a repos module that binds the base repo (see one row up). 
252
253
254
255
**licenses**
256
257
258
p. This folder holds a reference or copy of all licenses per library and module that is part of the distribution you installed. A browsable version of this content can be found on release page on the Wiki. For example, for version 2.9, go here: 
259
260
261
262
p. "https://redmine.z2-environment.net/projects/z2-environment/wiki/V2":https://redmine.z2-environment.net/projects/z2-environment/wiki/V29-Licenses "9":https://redmine.z2-environment.net/projects/z2-environment/wiki/V29-Licenses "-Licenses":https://redmine.z2-environment.net/projects/z2-environment/wiki/V29-Licenses 
263
264
265
266
p. Note: To our knowledge, there are no non-business-friendly OSS licenses, but you need to check for yourself.
267
268
269
270
**LICENSE.txt and THIRD-PARTY-LICENSES.txt**
271
272
273
p. The license you retrieved z2 under, the Apache 2 Open Source Software license, as well as information on how to find out about third-party licenses, just as above.
274
275
276
277
**work**
278
279
280
p. During runtime z2 needs to store essentially transient data like compilation results or other cached data. While a running z2 may not be able to handle a missing work folder, it is generally ok and sometimes even helpful to remove all transient work data when z2 is down. This folder is generated during runtime and not part of the distribution.
281
282
283
284
**data**
285
286
287
p. The data folder is used by applications that need to maintain local, file-system stored data, for longer. In short: The data folder should not be deleted casually and, depending on your application, it may be advisable to have it point to particularly reliable storage.
288
289
290
291
**logs**
292
293
294
p. The place to write log files to. Z2 itself writes its log output into logs/home_0_0.log.
295
296
297
298
p. A few files are important in the bin folder:
299
300
301
p. *runtime.properties*
302
303
304
p. The properties stored in runtime.properties are loaded by the home process and all worker processes into the respective JVM system properties. See also [[#Important System Properties|#systemProps]] .
305
306
307
p. *launch.properties*
308
309
310
p. A z2 home can be started in different “modes”. This is a convenience feature to simplify the application of various Virtual Machine settings for the home process (many of which propagate to worker processes – including debug settings).
311
312
313
p. A typical launch.properties file looks like this:
314
315
316
<pre><code class="bash">#
317
# alternative VM profiles for the home process
318
# VM opts
319
# default
320
#
321
home.vmopts=\
322
	-Xmx64M -cp z.jar \
323
	-Dcom.sun.management.config.file=management.properties \
324
	-Djava.util.logging.config.file=logging.properties \
325
	-Dcom.zfabrik.home.concurrency=5 \
326
	-Dcom.zfabrik.home.start=environment/home
327
328
# override when -mode debug
329
home.vmopts.debug=-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,suspend=n,server=y,address=5000 -Dworker.debug=true
330
331
# override when -mode verbose
332
home.vmopts.verbose=-verbose:gc -XX:+PrintClassHistogram
333
</code></pre>
334
335
336
337
h3. Starting and synchronizing
338
339
340
p. In order to start Z2 in server mode, change into the folder *Z2_HOME/bin*
341
342
343
p. If you prefer a simple console view, you can start the z2 Environment by issueing the command *./go.sh* (on Linux/Mac OS) or *go.bat** *(on Windows).
344
345
346
p. There are several options you may use to alter the default behavior. Most notably, if you start using 
347
348
349
<pre><code class="bash">	./go.sh -mode:debug  </code></pre>
350
351
352
p. the z2 Environment will start with debug settings (see launch.properties above).
353
354
355
p. If you start using
356
357
358
<pre><code class="bash">	./go.sh - -np</code></pre>
359
360
361
p. the home process will end up showing an input prompt – which is favorable to running as background process (e.g. using nohup or via an init script on Linux). And of course, if you run
362
363
364
<pre><code class="bash">	./go.sh -mode:debug - -np</code></pre>
365
366
367
p. you will get both.
368
369
370
p. The general syntax is
371
372
373
<pre><code class="bash">./go.sh <parameters for the launcher> - <parameters for the home process></code></pre>
374
375
376
p. where the launcher is the small program that computes the actual Java command line as indicated in the previous section.
377
378
379
p. When running the z2 Environment locally, in particular during application development, it is convenient to have a graphical user interface (GUI). Adding the *gui* option achieves just that. For example
380
381
382
p. 	./go.sh -mode:debug - -gui 
383
384
385
p. starts the home process with a Java GUI  that allows to scroll through the home and worker processes console output and to manage synchronizations as well as the current list of worker processes.
386
387
388
p. The gui shell command is a shortcut that spares you the *gui* option. I.e 
389
390
391
p. 	./gui.sh 
392
393
394
*is a short version of *.***/go.sh - -gui***.**
395
396
397
h3. *Important System Properties*
398
399
400
p. *Some system properties can be set on the command line (or launch.properties) or for all z2 processes (e. g. in runtime.properties, see **[[#Folder Structure of a Z2 Home|Folder Structure of a Z2 Home]] *).
401
402
403
| Property name| Meaning |
404
| com.zfabrik.mode| Set to “development” for development mode. Some features, such as test code and switchboard, will be ignored unless in development mode. This applies to the home process and worker processes. |
405
| com.zfabrik.offline| If set to true, enables the offline mode (see [[#Using the Offline Mode|#offlineMode]] ). Can be toggled on the GUI. Will be automatically propagated to worker processes at synchronization. |
406
| com.zfabrik.config| Name of the system config file to be loaded by all processes. Defaults to runtime.properties. This applies to the home process and worker processes. |
407
| com.zfabrik.home| The z2 Home folder, i.e. where the z2 core is installed.If not specified when starting Z2, this property is determined by checking for the environment variable Z2_HOME. If that is not set either, it defaults to “..”, one up from the current work folder, which is the installation folder, if you are in the bin folder of standard z2 Home folder structure.  |
408
| com.zfabrik.home.layout| Home layout to start by the home process. This determines the worker processes to start. Technically this will be appended to the setting com.zfabrik.home.start. This setting applies only to the home process.  |
409
| com.zfabrik.home.start| Comma separated list of dependency components (in particular system states) to prepare at start and after each synchronization by the home process. This setting applies only to the home process.  |
410
| com.zfabrik.java.level| Java language level used for compilation. Can be 6,7,8. Determined by the Java runtime in use. |
411
| com.zfabrik.home.autoVerifyInterval| Interval in seconds after which the home process will run a verification (an attempt to attain all target states) again. Defaults to none (undefined). This applies only to the home process. |
412
| com.zfabrik.dev.local.workspace| Setting of the development repository defining where to check for “armed” modules. See also [[#Workspace development using the Dev Repository |#devRepo]] . Relative to current working folder, which is typically the Z2_HOME/bin.  Typically set to “../../..”, i. e. in the direct neighborhood of Z2_HOME. This applies only to the home process. |
413
| com.zfabrik.dev.local.depth| Setting of the development repository defining how deep the Dev Repo scans for LOCAL files. Depth is measured in path distance from the roots set via the system property  com.zfabrik.dev.local.workspace. Defaults to 3. See also [[#Workspace development using the Dev Repository |#devRepo]] . |
414
| com.zfabrik.repo.mode| General repository access mode. If set to “relaxed”, repositories will attempt to work on previously cached resources in case of technical repository access failures during synchronization. If set to “strict” (which is the default), technical failures will lead to a failure in synchronization, even if local resources are available. This feature is useful for offline or bad connectivity situations.  |
415
416
417
418
p. Note see also [[#Worker Processes (z2-base)|#workerProcesses]]  on how to make sure properties are propagated to worker processes.  More important system properties, including some that will be set by z2 at runtime, can be found in the "Foundation":http://www.z2-environment.net/javadoc/com.zfabrik.core.api!2Fjava/api/com/zfabrik/util/runtime/Foundation.html  class.
419
420
421
h3. The Base Repository
422
423
424
p. The Z2 core that gets cloned (or checked out) to create a Z2 Home contains exactly what is needed to be able to bootstrap a running environment. All further definitions, code, and configuration is retrieved via additional component repositories that are typically accessed remotely. 
425
426
427
p. The starting point, from the perspective of the Z2 core is the so-called _Base Repository_.
428
429
430
p. The Base Repository is defined in *Z2_HOME/local/com.zfabrik.boot.config/baseRepository.properties. *By default the Base Repository points to the *z2-base.base* repository hosted on z2-environment.net. 
431
432
433
p. When you create your own system, this is an important customization point. We will get to that in [[#Constructing a Z2 system|Constructing a Z2 system]]  after we have learned a about [[#Components and Component Repositories|Components and Component Repositories]] .
434
435
436
h3. Worker Processes and Home Layouts
437
438
439
p. As indicated above the z2-Environment can manage further JVM processes to better support heterogeneous load scenarios without compromising the ability to apply updates consistently nor the stability of the home process
440
441
442
p. Worker processes are, from a home process perspective, regular z2 components. See also the documentation of the component type *com.zfabrik.worker* below. What makes worker processes special is their virtual machine configurations and the set of target system states to attain (see *com.zfabrik.systemState* below). System states, on the other hand, group components to be started and kept alive during synchronization and verification. 
443
444
445
p. When a worker process component is initialized (we say prepared), it starts a JVM, as configured, that loads another instance of the z2-environment that in turn attempts to attain the configured target system states.
446
447
448
p. Worker processes are typically prepared as dependency of a home layout. A home layout – by convention -  is simply a system state that is used to define the components that are expected to be prepared in a home process, initially and at the conclusion of a synchronization.
449
450
!{height:14.579cm;width:12.002cm;}10000201000003B10000047C0381106D3BD4ED46.png!
451
452
453
p. A typical home layout declaration for a single worker process to be executed looks like this:
454
455
456
p. com.zfabrik.component.type=com.zfabrik.systemState
457
458
com.zfabrik.component.dependencies=\
459
  environment/webWorker
460
461
462
p. Home layouts are useful to define node specific configurations running individual worker process configuration combinations from the very same shared configuration store to achieve maximum  functional flexibility in a distributed deployment without distributing configuration information. All that is required to start z2 with a given home layout is a change in command line settings.
463
464
465
h2. Anatomy
466
467
468
h3. Working on-demand
469
470
471
p. Much of the goodness of the Z2-Environment comes from the fact that it has a pervasive on-demand architecture. That means that whenever the runtime binds resources it is for a clear and understandable reason, either because a need (a dependency) has been declared or the specific task at hand requires so. 
472
473
474
p. While that sounds trivial, it is not so. Unlike implicit “start of everything deployed” or “everything in a list” approach that many application servers implement, binding of runtime resources from the potentially large pool of components available in a component repository (see below) happens strictly as required based on target states configuration – which eventually translates to simplified on-demand operations of large scale out scenarios with heterogeneous node assignments.
475
476
477
p. The sibling of the load-on-demand approach is the unload-on-invalidity approach. When repository definitions have been updated, in development but also in production scenarios, Z2 runtimes can adapt to the changes made. That requires to understand what component definitions have become invalid and to “unload” these from memory. Because of the modular nature of components and the heavy re-use of resource, invalidation of one component typically implies that others, dependant components have implicitly become invalid as well. 
478
479
480
p. For example, a change in an API  defined in some Java component may imply that web applications have to be restarted.
481
482
483
p. The abstraction for resources that have dependent resources is the Resource Management system of Z2.
484
485
486
h4. The Resource Management System
487
488
489
p. The Resource Management system is at the heart of the Z2 runtime. Essentially anything that binds runtime memory or represents components is internally modeled as extensions of the Resource class (see "Resource":http://www.z2-environment.net/javadoc/com.zfabrik.core.api!2Fjava/api/com/zfabrik/resources/provider/Resource.html ). 
490
491
492
p. Resources represent any kind of abstraction that may be made available for some time and that may have dependencies onto other abstract resources, such as cache regions, applications, etc. In particular z2 components are resources.
493
494
495
p. Resources are provided by Resource Providers that establish a namespace of resources. One of which is the components resource provider that uses the component factory mechanism to delegate resource construction further.
496
497
498
p. A resource can be asked for objects implementing or extending any given Java type using the "IResourceHandle":http://www.z2-environment.net/javadoc/com.zfabrik.core.api!2Fjava/api/com/zfabrik/resources/IResourceHandle.html  interface. For components, the IComponentsLookup.lookup method is simply a delegating facade to that.
499
500
501
p. A complete description of the resource management system is beyond the scope of this section. Please see the documentation of the com.zfabrik.resources packages in the " core API Javadocs":http://www.z2-environment.net/javadoc/com.zfabrik.core.api!2Fjava/api/index.html .
502
503
504
h4. The z2 Command Line, the Embedded Runtime and the Main Runner
505
506
507
p. The Z2 environment can be used as a multi-process server environment, which is what we looked at above, or embedded. The z2 command line that was used already in [[#Starting and synchronizing|Starting and synchronizing]]  is provided by the z.jar library in Z2_HOME/bin. Invoke
508
509
510
<pre><code class="bash">java -jar z.jar  -?</code></pre>
511
512
513
p. to see all options.
514
515
516
p. One particular way of using z2 that we want to look at in detail in this section is the embedded mode. Running it embedded simply means to initialize the resource management system and component system from within another JVM process.
517
518
519
p. This execution mode can be handy for various purposes:
520
521
* You can use it to run “Main” programs (see XYZ) that are defined in some component repository from the command line w/o worrying about local build environments (and dependency resolution)
522
* Sometimes you have no control over the execution mode because your code has been started by some other infrastructure. This is for example true for Hadoop Map-Reduce jobs. In that case the Hadoop Map-Reduce implementation starts tasks from a simple JAR file on some machine. Using the embedded mode we can execute Map-Reduce jobs defined in component repositories, without complicated job assembly into a hadoop job jar.
523
524
p. To facilitate the embedded mode, the Z2 launcher z.jar must be invoked accordingly.
525
526
527
p. Pre-requisite to using Z2 in an embedded way is to have a Z2 home installation in file system reach. That home installation will be used to cache component repository content and binaries – i.e. it is essential to actually implement Z2.
528
529
530
p. When you open a console and run
531
532
533
p. java -cp z.jar com.zfabrik.launch.MainRunner
534
535
536
p. you will get
537
538
539
<pre><code class="bash">z2 MainRunner: Main program execution of z2 components. 
540
541
SYNOPSIS 
542
543
java -DcomponentName=<component name> -cp z.jar MainRunner <args> 
544
545
OPTIONS 
546
547
   <component name> 
548
       A component name in Z2 identifying a main program component 
549
        
550
   <args> 
551
       Parameters passed to the main program 
552
553
NOTES 
554
555
Make sure to either set a Z2_HOME environment variable pointing to the  
556
relevant z2 home installation or specify the system property com.zfabrik.home 
557
when calling the MainRunner: 
558
559
java -DcomponentName=<component name> -Dcom.zfabrik.home=<home folder> -cp z.jar com.zfabrik.launch.MainRunner <args>
560
</code></pre>
561
562
563
p. explaining the most direct way of using the embedded mode.
564
565
566
p. There are several Main programs that come with the z2-base system. For example a tool to retrieve binaries from Z2: *com.zfabrik.dev.util/jarRetriever*
567
568
569
p. Running: 
570
571
572
p. java -DcomponentName=com.zfabrik.dev.util/jarRetriever -cp z.jar
573
com.zfabrik.launch.MainRunner -out test com.zfabrik.dev.util
574
575
576
p. Retrieves the binaries of the Java component *com.zfabrik.dev.util/java* into the folder *test*. See also "com.zfabrik.dev.util":http://www.z2-environment.net/javadoc/com.zfabrik.dev.util!2Fjava/impl/index.html . Note that the environment variable Z2_HOME was assumed to be set. Otherwise use the system property *com.zfabrik.home* to specify the home path.
577
578
579
p. *Compatibility note:* The z_embedded.jar used for embedded execution in previous z2 versions is still present and identical to z.jar except for its main-class com.zfabrik.launch.MainRunner.
580
581
582
p. Another way of embedded execution is programmatically via the "ProcessRunner":http://www.z2-environment.net/javadoc/com.zfabrik.core.api!2Fjava/api/com/zfabrik/launch/ProcessRunner.html  class.
583
584
585
h3. Components and Component Repositories
586
587
588
p. Everything you ever touch that the z2 Environment is supposed to understand is organized in _Components. _Z2 is built around the concept of named components that are defined in a well-defined repository structure. The level of understanding of resources that are used to implement some functionality in z2 is essential so that z2 understands when resources have been modified and corresponding runtime objects have become invalid and so that z2 is extensible by new semantics, that is new types of components.
589
590
591
p. More specifically the term Component translates in z2 to runtime objects that implement semantics according to a _Component Type_, have a well-defined, location-derived name, and are declared by a set of properties and optionally any kind of file type resources – e.g. holding the files of a Web Application.
592
593
594
p. Component properties are accessible within z2 via the IComponentsManager interface providing IComponentDescriptor instances.
595
596
597
p. Component properties are typically declared via *.properties file resources in stores backing component repositories such as Git, Subversion, or a file system.
598
599
600
p. Component properties can be declared in a static, non-computed way but also with some dynamic handling as descibed in [[#Dynamic Component Properties|Dynamic Component Properties]] .
601
602
603
p. Even more specifically, most existing Component Repositories implement the following folder structures that define components as shown in the right column: 
604
605
| …<module>/<local>.properties...| Defines component <module>/<local> of type of value of the property com.zfabrik.component.type as set in the property file <local>.properties. |
606
| ...<module>/<sub>/ 	z.properties	<file/folder>	<file/folder>	…...| Defines component <module>/<sub> of type of value of the property com.zfabrik.component.type as set in the property file z.properties.The component has furthermore all resources defined in all files and folders under <sub>.These can be accessed using IComponentsManager.INSTANCE.retrieve(<folder>/<sub>) |
607
608
609
610
p. The module taxonomy has no little technical meaning to Z2. There is no internal Object representing a module. Via conventions however the module (as being the path without its last segment) has a rather prominent function:
611
612
* Typically the module matches the development project granularity
613
* The resolution of Java resources for a component defaults to <module>/java (see [[#Java components (core)|Java components]] ).
614
* If two component repositories define components of an equally named module, no component of that module of the repository with the lower priority will be visible.
615
616
p. Component repositories define the reality for the z2 environment. So it is important to understand this concept to understand z2.
617
618
619
p. Component repositories are, of course, declared as components itself. Consequently, component repositories may hold further definitions of component repositories – potentially leading to some reality distortion (aka Bootstrapping) issues – in the rare case you do advanced repository wiring.
620
621
622
p. When the z2 Environment starts up it has a hard coded knowledge of the _Local Repository_ that is stored in *Z2_HOME/local* (see also above). It is the root of the Z2 component universe from a Z2 Home perspective. 
623
624
625
p. The Local Repository also defines the Base Repository, that we briefly touched on in [[#The Base Repository|The Base Repository]]  and will meet again in [[#Constructing a Z2 system|Constructing a Z2 system]] .
626
627
628
p. The following diagram is an overview over the few entities that really are the heart of Z2 core – from component repository to resource via synchronization:
629
630
!{height:6.189cm;width:17cm;}100002010000060D00000234C0ED4E95AC562BA6.png!
631
632
633
p. The notable exception to the repository structure above is Maven component repositories and – to some extent – the Hub Component Repository. The former derives Java components from Maven repository artifacts. That is, while the underlying structure is completely different, the repository implementation presents it in a Z2 compliant way (see [[#Maven Repository Support|Maven component repositories]] ).
634
635
636
p. The Hub Component Repository turns a Z2 system into a repository for another Z2 system with the purpose of reducing bandwidth requirements for the original repositories or to not send source code over the wire (see [[#The Binary Hub Component Repository|the Hub Component Repository]] ). 
637
638
639
h4. Synchronization with updates
640
641
642
p. At times, frequently when you are developing and less frequently in production, you want your runtimes to get up to date with respect to repository contents. That process is called _Synchronization. _The ability to synchronize with repositories is a particular capability of the z2-Environment and responsible for much of its goodness.
643
644
645
p. The synchronization process happens in three phases: At first, in the pre-invalidation phase, all component repositories (actually all “synchronizers”, but component repositories are generally connected to synchronizers. See also "ISynchronizer":http://www.z2-environment.net/javadoc/com.zfabrik.core.api!2Fjava/api/com/zfabrik/util/sync/ISynchronizer.html ) are asked to check whether there are updates available and what components (by name) will be affected. In the simplest case, the file system stored component repository, the check will examine folders to find out whether files have changed since the last time it was asked to check. 
646
647
648
p. When that phase has completed, all components that have been identified to be subject of updates will be invalidated. Invalidation is a concept of the Resource Management systerm underlying z2. Loosely speaking it means that a component is asked to let go of all state but its name. Anything that is dependent on repository content or other components it depended on is to be dropped.
649
650
651
p. In the completion phase of the synchronization, synchronizers are asked to make sure that at the end of the completion phase the runtime has attained operational modes again. That is maybe the most interesting phase, as actions to that end may greatly vary.
652
653
654
p. For example, the home synchronizer (*com.zfabrik.boot.main/homeSynchronizer*) will simply try to attain the home_up state again.
655
656
657
p. The worker synchronizer (*com.zfabrik.workers/workerSynchronizer*) will send all invalidations to the worker processes and then ask them to attain their target states again.
658
659
660
p. Note that synchronizers have a priority and are called in a defined order. So that the worker synchronizer is called before the home synchronizer. As worker processes may have been invalidated in the second phase, it would be unreasonable to first bring them up again (home synchronizer) just to tell them about invalidations once more.
661
662
663
h4. File system support
664
665
666
p. The simplest of all built-in component repositories is the file system component repository. All that is required is a file system folder holding component declarations and component resources in a structure as described above. As laid out below, always make sure the repository is started early on by declaring a participation in the system state *com.zfabrik.boot.main/sysrepo_up*.
667
668
669
p. See [[#File system component repositories (core)|File system component repositories]]  for more details on the configuration of file system component repositories.
670
671
672
_Subversion support_
673
674
675
p. The popular source control management system Subversion (see "www.tigris.org":http://www.tigris.org/ ) was the first repository supported by z2 and still shines in many aspects. 
676
677
678
p. In order to add a subversion component repository, declare a component of type *com.zfabrik.svncr** *as described in [[#Subversion component repositories (core)|Subversion component repositories]] .
679
680
681
p. To avoid problematic licenses, the z2 Environment does unfurtunately not come with the complete built-in Subversion connectivity. Additional configuration steps are required once to complete subservion enabling on your side, as described in the "Subversion How-To":https://redmine.z2-environment.net/projects/z2-environment/wiki/How_to_Subversion .
682
683
684
p. As noted above, it is important to make sure your repository participates in the system state *com.zfabrik.boot.main/sysrepo_up*, i.e. you should add the line
685
686
687
<pre><code class="bash">com.zfabrik.systemStates.participation=com.zfabrik.boot.main/sysrepo_up</code></pre>
688
689
690
p. to the repository declaration. The URL of the repository should point to a repository folder structure  as outlined in [[#Components and Component Repositories|Components and Component Repositories]] . For example, the Base Repository of the z2@base distribution has the URL: 
691
692
693
<pre><code class="bash">http://z2-environment.net/svn/z2-environment/trunk/z2-base.base</code></pre>
694
695
696
h4. Git support
697
698
699
p. The GIT version control system (VCS) is an implementation of a distributed version control system (DVCS). As opposed to centralized VCS, such as Subversion below, in a DVCS users hold a copy (called a _clone_) of the repository content on their local environment, typically the local disk, and can execute all typical modification operations, such as adding files, committing changes, to the Local Repository before sending updates back to a remote repository or retrieving updates from a remote repository.
700
701
702
p. Currently all framework development for Z2 happens in Git. All results are however available from Subversion repositories as well.
703
704
705
p. From a Z2 perspective a DVCS has the advantage of giving a  slightly easier way of getting your own local repository that is fully under your control. Also moving changes between systems has a built-in solution this way. On the downside, you pay by distributing complete copies of your system's repository which may turn into a problem once repositories get significantly bigger than what is actually needed for the given scenario. That's why there is an implied tendency for more and smaller repositories when using Git und fewer but larger repositories when using Subversion.
706
707
708
p. In order to add a Git component repository, declare a component of type *com.zfabrik.gitcr *as described in [[#GIT component repositories (core)|GIT component repositories ]] .
709
710
711
p. As noted before, it is important to make sure your repository participates in the system state *com.zfabrik.boot.main/sysrepo_up*, i.e. you should add the line
712
713
714
<pre><code class="bash">com.zfabrik.systemStates.participation=com.zfabrik.boot.main/sysrepo_up</code></pre>
715
716
717
p. to the repository declaration. 
718
719
720
h4. Maven Repository Support
721
722
723
p. Maven repositories such as "Maven Central":http://search.maven.org/  are a huge source of open-source libraries made available directly by the copyright holder. Maven repositories can be integrated into a Z2 system as component repositories. In fact, most of the samples accessible from the Z2 Wiki as well as prominent add-ons such as the Hibernate and Spring add-on make use of this approach.
724
725
726
p. 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.
727
728
729
p. Artefacts in Maven repos have a fully qualified name of the form
730
731
732
<pre><code class="bash"><groupId>:<artifactId>:<version></code></pre>
733
734
735
p. or
736
737
738
<pre><code class="bash"><groupId>:<artifactId>:<packaging>:<version></code></pre>
739
740
741
p. By default, a jar artifact *<groupId>:<artifactId>:<version>* will result into a Java component of name
742
743
744
<pre><code class="bash"><groupId>:<artifactId>/java</code></pre>
745
746
747
p. As usual with Maven, if resolution root artifacts and dependencies lead to artifacts of the same packaging, group id, and artifact id but with different versions, a conflict resolution takes place (the higher version number will be used). 
748
749
750
p. 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.
751
752
753
p. The z2 core will use lazy component class loaders to make sure that use of include libraries has virtually no runtime penalty.
754
755
756
p. An example configuration of a component repository from a Maven artifact repository may look like this:
757
758
759
<pre><code class="bash">com.zfabrik.systemStates.participation=com.zfabrik.boot.main/sysrepo_up
760
com.zfabrik.component.type=com.zfabrik.mvncr
761
762
mvncr.repository=mavenDefault
763
mvncr.priority=200
764
mvncr.roots=\
765
  org.springframework:spring-context:4.0.2.RELEASE,\
766
  org.springframework:spring-aspects:4.0.2.RELEASE,\
767
  org.springframework:spring-tx:4.0.2.RELEASE,\
768
  org.springframework:spring-orm:4.0.2.RELEASE,\
769
  org.springframework:spring-web:4.0.2.RELEASE,\
770
  org.springframework.security:spring-security-core:3.2.2.RELEASE,\
771
  org.springframework.security:spring-security-web:3.2.2.RELEASE,\
772
  org.springframework.security:spring-security-config:3.2.2.RELEASE,\
773
  org.springframework.security:spring-security-aspects:3.2.2.RELEASE,\
774
  org.hibernate:hibernate-entitymanager:4.3.4.Final,\
775
  aopalliance:aopalliance:1.0,\
776
  org.aspectj:aspectjweaver:1.7.4,\
777
  org.aspectj:aspectjtools:1.6.9,\
778
779
mvncr.excluded=\
780
  org.jboss.spec.javax.transaction:jboss-transaction-api_1.2_spec
781
782
mvncr.managed=\
783
  commons-logging:commons-logging:1.1.2</code></pre>
784
785
786
p. This configuration would imply that the listed roots and all non-optional compile time references would be added as Java components with mapped references as described above. As an exception however, the artifact *org.jboss.spec.javax.transaction:jboss-transaction-api_1.2_spec* would be excluded. Furthermore, the artifact *commons-logging:commons-logging* would exclusively be used in version 1.1.2. Note: Those modifications of the dependency graph resolution correspond to similar Maven configurations (notably as in <exclusions> and <dependencyManagement>).
787
788
789
p. See [[#Maven component repositories (z2-base)|Maven component repositories]]  in the component reference for more details on configuration properties of Maven component repositories.
790
791
792
p. 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.
793
794
795
p. This is achieved by using Fragments of a  Maven component repository.
796
797
798
p. A fragments adds to the dependency graph but does not define where dependencies are retrieved from, so that the requirement for artifacts can be expressed without wiring the actual system to a specific environment. This is how the standard add-ons express their requirements.
799
800
801
p. 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.
802
803
804
p. In order to add a fragment to a Maven Component Repository declare a component of type *com.zfabrik.mvncr.fragment*.
805
806
807
p. See [[#Maven component repository fragments (z2-base)|Maven component repository fragments]]  in the component reference for more details on configuration properties for fragments.
808
809
810
p. 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.
811
812
813
p. Z2's implementation is based on "Eclipse-Aether":https://eclipse.org/aether/ .
814
815
816
p. As this subject is not completely trivial it is strongly recommended to check out the samples and explanations on the Wiki. Start with the "Maven Component Repository How-to":https://redmine.z2-environment.net/projects/z2-environment/wiki/How_to_Access_a_Maven_Repository .
817
818
819
p. As noted before, it is important to make sure your repository participates in the system state *com.zfabrik.boot.main/sysrepo_up*, i.e. you should add the line
820
821
822
p. com.zfabrik.systemStates.participation=com.zfabrik.boot.main/sysrepo_up
823
824
825
p. to the repository declaration. 
826
827
828
h4. Component Types and Component Factories
829
830
831
p. Every component in Z2 has a type, declared via the component property com.zfabrik.component.type. As indicated above the component type identifies the semantics of a component, i.e. how to treat it and what you can do with it. For example a web application is of type *com.zfabrik.ee.webapp*. Being of that type implies an expected folder structure for the resources that belong to the web application. Also it implies the ability to be made available via a web server. The semantics of a Java component (of type *com.zfabrik.java*) is obviously completely different.
832
833
834
p. _Component Factories_ are in charge of implementing the semantics of a component type. In short a whenever a component is requested via the resource management system, the component factory responsible for the respective component type is asked to create an implementation, more specifically a Resource (see [[#The Resource Management System|The Resource Management System]] ) that implements the actual component. 
835
836
837
p. So, for example, the component factory for web applications knows how to interpret the folder structure of a web application component as the layout of a Java EE web application and how to register this web application with the Jetty web container. The component factory for Java components knows how to check whether code needs to be compiled and how and how to set up class loaders.
838
839
840
h4. Dynamic Component Properties
841
842
843
p. Component properties can be specified to be dynamically evaluated at runtime. I.e. instead of assigning a static string value, input is specified that is processed by custom code before assigned as value to the property.
844
845
846
p. The most obvious use-case for this feature is to support property values that are derived from system properties, process environment variables, or properties of some other component. Built-in support for these use-cases is provided by the JEXL3 processor based on the Apache JEXL library ("http://commons.apache.org/proper/commons-jexl/":http://commons.apache.org/proper/commons-jexl/ ) version 3. See also [[#Using Dynamic Property Expressions with JEXL3|#jexl3support]]  for details.
847
848
849
p. In order to have property values evaluated in a non-static way, the property is extended by a processor type identifier:
850
851
852
<pre><code class="bash"><property name>:<processor type>=<expression></code></pre>
853
854
855
p. with a default processor type “plain”.
856
857
858
p. For example, a propery file, 
859
860
861
<pre><code class="bash">svncr.uri\:plain=http://myserver/svn/myrepo</code></pre>
862
863
864
p. is equivalent to 
865
866
867
<pre><code class="bash">svncr.uri=http://myserver/svn/myrepo</code></pre>
868
869
870
p. (note that the colon “:” character needs to be escaped with a leading backslash “\” in property file syntax so that it is not taken for a separator of name and value).
871
872
873
p. However, 
874
875
876
<pre><code class="bash">svncr.uri\:JEXL3=env.SVN_REPO+”/myrepo”</code></pre>
877
878
879
p. will evaluate the environment variable *SVN_REPO* and append a string “/myrepo” (see also [[#Using Dynamic Property Expressions with JEXL3|#jexl3support]] ).
880
881
882
883
p. Due to a number of reasons, the use of dynamic property evaluation is subject to various constraints:
884
885
* As a principle, when using the IComponentDescriptor API, getProperties() returns processed properties while the method getRawProperties() returns the unprocessed component properties in its original verbatim form.
886
* Processing of properties happens after retrieving properties from the original or intermediate storage, and in particular evaluation results will not be kept between component loading. That is, at latest after a restart and also after an invalidation due to a synchronization, component expressions will be evaluated again. However, after loading and as long as held onto during runtime nor repeated evaluation will be performed.
887
* The IComponentsManager findComponents(...) API is using raw component properties to find components based on search conditions. That is, a dynamic expression cannot be used to alter search results for extension points or component type implementations.
888
* When making use of dynamic properties early in the z2 loading life cycle, in particular in conjunction with component repository definitions and custom component descriptor processor implementations, particular care needs to be paid  to the availability of the processor at time of evaluation of component repository declaration.
889
890
h4. Using Dynamic Property Expressions with JEXL3
891
892
893
p. A component descriptor processor with processing type “JEXL3” comes built-in with z2 starting version 2.5. This processor is based on the Apache Commons JEXL library version 3.0 (see "https://commons.apache.org/proper/commons-jexl":https://commons.apache.org/proper/commons-jexl ). All values of properties tagged as of JEXL3 processing style in the original component descriptor source will be considered JEXL expressions.
894
895
896
p.  If evaluating to a non-null value, the expression evaluation result will be set as resulting property value of the same property name. If the expression evaluates to *null*, the corresponding property will not be set in the overall evaluation result.
897
898
899
p. The following implicit variables are made available by this processor:
900
901
902
| Variable name| Definition| Example |
903
| system| System.getProperties()| `user dir is ${system["user.dir"]}` |
904
| env| System.getenv()| "JAVA_HOME is ${env.JAVA_HOME}" |
905
| this| The actual property set in its evaluated form. This may be used to resolve properties that are again computed by some processor. Note that a max evaluation depth of 50 is enforced when resolving properties defined in the property set| this[“com.zfabrik.component.type”] |
906
| components| IComponentsManager.INSTANCE| components.getComponent("mymodule/mycomponent").getProperty("myProp") |
907
908
909
910
p. Using the *this* variable, re-use of definitions within a single descriptor is possible. For example, assuming even the involvement of some other processor _ext_, a property set
911
912
913
<pre><code class="bash">hostName\:JEXl3=env.hostName
914
database\:ext=_THE_DB_
915
ds.prop.url\:JEXl3=`jdbc:derby://${this.hostName}/${this.database}`</code></pre>
916
917
918
p. would be evaluated resolving across processors and with correct substitution in the JEXL expression.
919
920
921
p. Note that a JEXL expression does not necessarily evaluate to a string object. Neither is the input property value to be processed considered a JEXL string. For example, the expression
922
923
924
<pre><code class="bash"> `Hallo this is ${system["user.name"]}`</code></pre>
925
926
927
p. does indeed evaluate to a string. As does
928
929
930
<pre><code class="bash"> "Hallo this is ${system[\"user.name\"]}"</code></pre>
931
932
933
p. (without processing the ${} expression) and more advanced
934
935
936
<pre><code class="bash">system["os.name"].startsWith("Linux")? "We are running on a Linux OS" : "We are running on something else"</code></pre>
937
938
939
p. but not
940
941
942
<pre><code class="bash">500+10</code></pre>
943
944
945
p.  which is indeed an integer.
946
947
948
p. See also "https://commons.apache.org/proper/commons-jexl/reference/syntax.html":https://commons.apache.org/proper/commons-jexl/reference/syntax.html  for more syntax information.
949
950
951
h4. Java Naming and Directory Interface (JNDI) support
952
953
954
p. Components in the z2-Environment may be looked up via JNDI. The functionality is essentially equivalent to lookups via the *IComponentsLookup* interface.
955
956
957
p. When looking up a component, it is typically required to specify the expected return type. When using JNDI URLs this can be accomplished via a *type* query parameter. For example, when looking up a JDBC data source (see [[#Data Source components (z2-base)|Data Source Components]] ) that is declared in a component repository as the component *mymodule/dataSource*, the call
958
959
960
<pre><code class="java">IComponentsLookup.INSTANCE.lookup("mymodule/dataSource",javax.sql.DataSource.class); </code></pre>
961
962
963
p. is equivalent to 
964
965
966
<pre><code class="bash">new InitialContext().lookup("components:mymodule/dataSource?type=javax.sql.DataSource");</code></pre>
967
968
969
p. and both calls return a (shared) data source instance.
970
971
972
h4. Link Components and Component Linking
973
974
975
p. At times it can be useful to make an existing component definition available under another module and component name. This can be achieved using link components.
976
977
978
p. An important example is the construction environments from base environments as implemented by the sample applications. By convention the environment module contains actual runtime configuration for the web server, database datasources, user realms and in particular system states and worker process configurations. If we want to use different subsets of these configurations, e.g. because we define different systems based on the same basic distribution, we could copy and adapt the environment. That may however require to keep copies of complex configuration sets that would need to be updated once the underlying, shared, implementation changes. To mitigate that components may be linked similarly to symbolic links in Linux file systems.
979
980
981
p. In the case of the sample systems, components from the z2-base.base *environment_base* module are combined into a custom *environment* module by linking those required and overwriting those modified. This saves duplication of the web server and worker configurations for example, while we keep the home layout configuration.
982
983
984
p. In order to declare a link component, define a component of type *com.zfabrik.link* and supply a target component using the *link.targetComponent* property. For example, re-using a web server configuration from the environment_base module would look like this:
985
986
987
<pre><code class="bash">#
988
# link to environment.base for defaulting
989
#
990
com.zfabrik.component.type=com.zfabrik.link
991
link.targetComponent=environment.base/webServer</code></pre>
992
993
994
995
p. Link components are built-in with z2’s component handling and operations are delegated to declared target components:
996
997
* Lookup as implementation of an interface or class via e.g. IResourceHandle.as(…) or IComponentsLookup.lookup(…) in general (see the exception below).
998
* Component resource access via e.g. IComponentsManager.retrieve(…).
999
1000
p. Some operations are not delegated however:
1001
1002
* Lookup as IResourceHandle or IResourceObserver
1003
* Component Descriptor retrieval via IComponentsManager.get()
1004
* Search of components via IComponentsManager.findComponents(…).
1005
1006
1007
p. This leads to subtle but meaningful and important differences in behavior when working with linked components vs. working with ordinary components. For example, in the case of a linked component, a lookup for *IComponentDescriptor* would result in the descriptor of the target component, while a call to I*ComponentsManager.get() *for the same component would return the descriptor of the link component.
1008
1009
1010
p. A target component may itself be a link component. Where link resolution is implemented, it is done indefinitely until reaching an ordinary component. 
1011
1012
1013
h3. Unit of Work and transaction management
1014
1015
1016
p. The z2-Environment does not mandate any specific way of implementing transaction management. 
1017
1018
1019
p. It does however have a concept of a _unit of work_ that is used by parts of its implementation and that is the underpinning of the simple, but rather useful, built-in Java Transaction API (JTA) implementation.
1020
1021
1022
p. A unit of work is a well-defined part of the control flow on one thread of execution that resources such as database connections can bind to and learn about whether all work should be committed or rolled back at the end of it. The "WorkUnit API":http://www.z2-environment.net/javadoc/com.zfabrik.core.api!2Fjava/api/com/zfabrik/work/WorkUnit.html  that is part of the Z2 core APIs implements this abstraction. 
1023
1024
1025
p. All threads managed by the z2-Environment wrap their work using this API and when extending the  z2-Environment with custom threading implementations, it is suggested that you wrap the actual work using the WorkUnit API, so that at least the z2 infrastructure can integrate cleanly and optimize resource usage.
1026
1027
1028
p. The JTA implementation provided in the module *com.zfabrik.jta* provides a standard UserTransaction implementation that integrates with the WorkUnit API and thereby provides a robust transaction management abstraction that greatly simplifies integration with persistence tools like Hibernate JPA.
1029
1030
1031
p. It can be looked up using the global JNDI name 
1032
1033
1034
<pre><code class="bash">components:com.zfabrik.jta/userTransaction</code></pre>
1035
1036
1037
p. Note that *com.zfabrik.jta* is not a full-blown transaction manager that supports distributed transactions and corresponding protocols. It is fine for typical non-distributed transaction situations however.
1038
1039
1040
p. In conjunction with the z2 provided database connection pooling (see [[#ZFabrikPoolingDataSource|ZFabrikPoolingDataSource]] ) it is important to note that, if you choose work unit enlisting, then the WorkUnit abstraction defines transaction boundaries, so that automatically all database connections are enlisted with the current unit of work and committed or rolled back under control of the WorkUnit implementation.
1041
1042
1043
p. In terms of the JTA implementation, this behaves as if there is already a transaction open on the thread. 
1044
1045
1046
p. The WorkUnit API supports nesting and suspending of units of work. With the JTA implementation this corresponds to nested and isolated transactions.
1047
1048
1049
p. Please visit the Wiki page on transaction handling in Z2 to learn more about alternatives and how to integrate with a full-fletched transaction manager.
1050
1051
1052
h2. Constructing a Z2 system
1053
1054
1055
p. This section describes how Z2 systems are assembled from repositories and how to construct your own system from what is provided on z2-Environment.net and your own repositories.
1056
1057
1058
p. From a Z2 Core perspective it all starts with the Local Repository that is part of the core. In there, we define at least the Base Repository. The Base Repository typically points to some remote Git or Subversion based repository. Once Z2 has registered that repository, other repository may have appeared that will be registered as well which may lead to the appearance of yet more repositories and so on. Hence, in effect, we have a chain or tree of repositories with the Local Repository on its root as far as repositories contain declarations of repositories. 
1059
1060
1061
p. On the other hand, repositories have a priority (more on that below) that determine what repository has the right to say what a module contains. 
1062
1063
1064
p. Based on that mechanism you can construct a system definitions that consist of as few as one repository (if we do not count the core) or many repositories of which some are even shared between systems.
1065
1066
1067
p. Before moving forward on that, let's have a look at the add-ons. 
1068
1069
1070
h3. Add-ons
1071
1072
1073
p. Add-ons add more functionality to Z2. Generally speaking, an add-on is a regular Git or Subversion  repository that holds one or more modules and is incorporated into a z2-Environment defined system via a component repository declaration (see [[#Components and Component Repositories|Components and Component Repositories]] ).
1074
1075
1076
p. In other words, technically there is nothing particular about add-ons. It is the way they are used that is noteworthy. The idea is that you can pick the add-ons you need and add them on top of z2-base. Previously Z2 was available in distributions. Now you take z2-base and add what you need on top. 
1077
1078
1079
p. Add-ons provided on z2-environment.net are versioned just like z2-base, so that there is no complicated version vector.  Also add-ons have some documentation in the z2-Environment Wiki and come with some samples.
1080
1081
1082
h2. Developing with the z2-Environment
1083
1084
1085
p. So far we have learned about the principles behind the z2-Environment and how to configure and run it. This section is devoted to the development using Z2.
1086
1087
1088
p. In principle you would not need any tool support. You could simply check out files from your favorite repository, use some text editor or your favorite integrated development environment to add projects and files or to modify files as you wish, commit your changes and synchronize the runtime that would do whatever else is needed.
1089
1090
1091
p. While that is good news already, there are some simple tools that make your life still easier and give you a development experience you have probably not experienced before in Java environments.
1092
1093
1094
p. The whole approach to local development using the z2-Environment is currently based on two tools:
1095
1096
* The Development Repository – a component repository implementation that allows you to selectively and quickly test modifications
1097
* The Eclipsoid Eclipse plug-in. A plug-in to the popular Eclipse development environment that resolves project dependencies from a running z2-Environment.
1098
1099
h3. A note on what JDK to use
1100
1101
1102
p. Different Z2 versions support or require different Java versions. 
1103
1104
1105
| Z2 Version| Supported Java Versions| Highest Supported Language Level |
1106
| < 2.4| 1.6, 1.7| 1.6 |
1107
| 2.4, 2.5| 1.8| 1.8 |
1108
| 2.6| 9-10| 9 |
1109
| 2.7| 9-11| 11 |
1110
| 2.8| 9-13| 13 |
1111
| 2.9| 11-16| 15 |
1112
1113
1114
1115
p. As Z2 compiles Java code, it has to make a decision on what language level to compile for. Typically however you do not need to worry about this, as by default, Z2 simply sticks to the version of the Java Development Kit (or Java Runtime Environment) it is currently executed with.
1116
1117
1118
p. In general z2 will use the language level of the current runtime environment as long as that is within range of the lowest supported Java version and the highest supported language level.
1119
1120
1121
p. When using a higher, future Java version, version 2.5 will fall back to assuming Java 8 language. Version 2.6 and later will assume the language level of whatever is the highest supported version possible
1122
1123
1124
p. You can however enforce a language level to compile with using the system property *com.zfabrik.java.level*. Valid values are “1.6”,”1.7”, “1.8”, “9”, “10”, “11”,”12”,”13”, and so on for the respective Java version.
1125
1126
1127
h3. Workspace development using the Dev Repository 
1128
1129
1130
p. The Development Repository (or short Dev Repo), works by checking a file system folder for project sub folders that contain a file called *LOCAL* and scans for components inside. 
1131
1132
1133
p. It expects to find a component repository structure as detailed in  [[#Components and Component Repositories|Components and Component Repositories]] . 
1134
1135
1136
p. The Dev Repo has a high priority within the chain of component repositories. That means that whatever it finds, it will typically win against definitions provided from other component repositories.
1137
1138
1139
p. By default, the Dev Repo is configured to look for changes in sub folders (three levels deep by default - but see below) of the folder that contains the core installation. That is the reason behind the folder structure described in the next section:
1140
1141
1142
p. When using subversion and checking out the Z2 core into your Eclipse workspace the Dev Repo will find your projects. When using Git and importing projects from a working tree of a repository that is next to the Z2 core, the Dev Repo will find your projects as well.
1143
1144
1145
p. This is how it all ties together: Given the Dev Repo is able to find your project (that means a module to z2 if accepted), you simply put file called *LOCAL* into the project's root folder and the project and all its components will be picked up with preference by the Dev Repo next time you trigger a synchronization.
1146
1147
1148
p. That sounded a little complex, but as you will see next, together with the Eclipsoid tool it all rounds up nicely.
1149
1150
1151
p. Before going there it is noteworthy that the Development Component Repository has use cases beyond development. Sometimes it handy to override centrally defined components, for example to modify web server ports or data source configurations, via the Dev Repo. 
1152
1153
1154
p. By modifying the system property *com.zfabrik.dev.local.workspace* you can influence where the Dev Repo scans for armed modules.
1155
1156
1157
p. Using the system property *com.zfabrik.dev.local.depth* you can influence how _deep_ the Dev Repo scans for LOCAL files. Depth is measured in path distance from the roots set via the system property  *com.zfabrik.dev.local.workspace*. This setting defaults to a value of 3, which means that 
1158
1159
1160
p. folder1/folder2/folder3/LOCAL
1161
1162
1163
p. would be found, which would then make up for module *folder3*.
1164
1165
1166
*Recommended folder structure *
1167
1168
1169
p. Using Git or Subversion makes no difference in the non-development folder layout of a Z2 installation. In development however there is a small but noticeable difference.
1170
1171
1172
p. In a Subversion setup, the folder that holds the Z2 core check out is also used as development workspace. That is, you will have a workspace folder, say *workspace* and in that workspace the Z2 core checkout as well as other projects, typically corresponding to Z2 modules as far as Z2 is concerned. E.g.:
1173
1174
1175
<pre><code class="bash">workspace/z2-base.core
1176
workspace/com.acme.some.project
1177
...</code></pre>
1178
1179
1180
p. In a Git setup, the development workspace folder is a folder next to the clone of the Z2 core repository. Assuming you installed into *install* and the workspace folder is called *workspace* your structure would look like this:
1181
1182
1183
p. install/z2-base.core
1184
install/some.other.repo.clone
1185
install/workspace
1186
...
1187
1188
1189
p. Note: In both cases, the search path for “armed” project is the same for the Development Repository  (see above).
1190
1191
1192
h3. The Eclipsoid Plug-in
1193
1194
1195
p. The Eclipsoid plug-in for the Eclipse development environment comes with the z2-base system and can be installed from the local update site at 
1196
1197
1198
*http://localhost:8080/eclipsoid/update/site.xml*
1199
1200
1201
p. Alternatively, you can install it from the z2 environment server at
1202
1203
1204
*http://www.z2-environment.net/eclipsoid/update/site.xml*
1205
1206
1207
p. This plug-in provides a number of useful utilities for working with Z2. The most important functions are:
1208
1209
# Trigger synchronization of the running z2-Environment from the IDE (Sync)
1210
# Download of dependencies as .jar files from a running z2-Environment (Resolve)
1211
1212
1213
p. The Eclipsoid fixes an important problem in development of larger software systems in IDEs like Eclipse:  Larger software systems consist of many different projects that have compilation dependencies between each other. That is, Java code in one project may not compile without having access to Java types defined in another project. 
1214
1215
1216
p. IDE's like Eclipse support local compilation of the code you are working on and show compilation problems early on. To do so however, the project's dependencies need to be resolvable. That is exactly what the Eclipsoid does: Upon _Resolve_, any Eclipse Java project that is recognized as a Z2 project will be introspected for Java components (see [[#Java components (core)|Java Components]] ), and if found, their references will be resolved from the server-side and required Java definitions will be downloaded and provided to the project.
1217
1218
1219
p. Technically, a Z2 project is any Java project that has the Z2 Class path Container (called "ZFabrik.Eclipsoid") in its class path (i.e.  the “.classpath” file). You do not need to fix that by yourself though. Either by creating a project as Z2 project or by “Transform into Z2-project” you can let the plug-in do that for you.
1220
1221
1222
p. That means: In order to work on a single project, from a possibly large solution, you check out that single project, invoke _Resolve_, and, from there on, modify and _Sync_ repeatedly to test your modifications. When you are done you commit your changes and disarm projects again to make sure the integrated content is effective.
1223
1224
1225
p. The last step is actually somewhat depending on your setup. If your Z2 is hooked up with remote Git repositories, you may need to push changes to remote before.
1226
1227
1228
!{height:10.795cm;width:15.201cm;}10000201000004AD00000352DFAA25D9150C0C7B.png!
1229
1230
p. _Sync_ and _Resolve_ can be invoked by pressing Alt+Y or Alt+R respectively or by clicking on the Z2 toolbar buttons. 
1231
1232
1233
p. Finally, the Eclipsoid can _arm_ and _disarm_ projects: Arming a project means to put an empty *LOCAL* file into it, and disarming means to remove that file again. 
1234
1235
1236
p. See the previous section for more details on the Dev Repo. Armed projects are shown with a green halo around the Z decoration in the project view.
1237
1238
1239
h3. Using the Offline Mode
1240
1241
1242
p. One principle feature of Z2 is to provide for early integration across a team of developers using a central repository containing the latest changes – except for those modules you are currently working on by virtue of the development repository.
1243
1244
1245
p. At times this can get in the way of productivity though. In particular when you find yourself in a situation of unreliable network connectivity.
1246
1247
1248
p. For those cases you can turn Z2 into an offline mode during which component repository implementations will not attempt to fetch updates from non-local sources.
1249
1250
1251
h4. How the offline mode is used. 
1252
1253
1254
p. The offline mode is enabled or disabled by setting the system property *com.zfabrik.offline* to *"true"* or *"false"* respectively. The default value of this property is "false". 
1255
1256
1257
p. This works regardlessly of how this system property is set in the home process. Worker processes receive an updated value upon synchronization. 
1258
1259
1260
h4. Enabling Offline mode at start time 
1261
1262
1263
p. Using the file *<Z2 home>/bin/runtime.properties* the offline mode can be enabled at starting time already. Note however that typically some collected offline content needs to be retrieved before working with a z2 system makes sense during development.
1264
1265
1266
h4. Toggling Offline Mode during Development 
1267
1268
1269
p. Alternatively the offline mode may be switched on or off using a check box on the Z2 GUI.
1270
1271
1272
h3. In-container unit testing using Z2 Jupiter
1273
1274
1275
p. The Z2 Jupiter feature of z2-base.base allow to run _in-system_ tests on z2, from anywhere where you can run JUnit tests. To learn more about the JUnit testing framework, please visit "http://www.junit.org":http://www.junit.org/ .
1276
1277
1278
p. In-system tests are ordinary unit tests that run within the server environment. Running tests within the running environment is also called integration testing.
1279
1280
1281
p. Standard JUnit tests run in an environment that often has little to do with the tested code's "native" environment, other than seeing the same types. Anything else, database connectivity, domain test data, component and naming abstractions (e.g. JNDI) need to be firstly abstracted out from the tested code and secondly mocked, that is, simulated one way or the other, into the test assembly of things.
1282
1283
1284
p. While that has the advantage of a defined, clean-room test bed, for higher-level components this can become unreasonable and assuring the correctness of the mocked up environment becomes a testing issue on its own.
1285
1286
1287
p. The Z2 Jupiter feature is built on the JUnit 5 API that succeeded the JUnit 4 API that is the underlying foundation of the previously promoted z2Unit feature (see "How to z2Unit":https://redmine.z2-environment.net/projects/z2-environment/wiki/How_to_z2Unit ). It is recommended that you use the z2 Jupiter implementation starting with z2 Version 2.9.
1288
1289
1290
p. At the heart of Z2 Jupiter lies the Z2 Jupiter Test Engine implementation that delegate test discovery and test execution to a running z2 server runtime. That is, although JUnit believes to run a locally defined test class, the actual test execution is performed in another process, running the test methods and reporting results back to the client.
1291
1292
1293
p. Please visit the "How to unit test in Z2":https://redmine.z2-environment.net/projects/z2-environment/wiki/How_to_Unit_Test_in_Z2 " ":https://redmine.z2-environment.net/projects/z2-environment/wiki/How_to_Unit_Test_in_Z2 Wiki page on z2Unit to learn how to practically use Z2 Jupiter.
1294
1295
1296
p. If you want to automate tests and cannot rely on the Eclipsoid to have a suitable class path, you should use the **com.zfabrik.dev.util/jarRetriever** tool to retrieve all required dependencies. In that case, you can run Z2 Jupiter tests just as any unit tests also from an "ANT":https://ant.apache.org/ " ":https://ant.apache.org/ script for example. A typical application is to run Z2 Jupiter integration tests as part of your test automation effort.
1297
1298
1299
p. See in particular the following section on how to download dependency libraries from Z2 for use with ANT.
1300
1301
1302
h3. Retrieving jars from Z2
1303
1304
1305
p. In most everyday operations you do not need to think about binary build results when using the Z2 environment. Sometimes however, in particular when running or inspecting code outside of Z2 you it is required to have compiled binaries at hand.
1306
1307
1308
p. Using the *com.zfabrik.dev.util/jarRetriever* tool you can request binaries of a set of Java components including dependencies. This tool is an example of a Main program running using an embedded Z2 environment. That is, in order to run it you do not need a Z2 server running. You do however need a Z2 home installation.
1309
1310
1311
p. See "JarRetriever":http://www.z2-environment.net/javadoc/com.zfabrik.dev.util!2Fjava/impl/com/zfabrik/impl/dev/JarRetriever.html  for more info on the jarRetriever. Also see [[#The z2 Command Line, the Embedded Runtime and the Main Runner|The z2 Command Line, the Embedded Runtime and the Main Runner]]  for more info on the embedded mode and the MainRunner.
1312
1313
1314
p. One particular use case is to retrieve Jars from Z2 within an ANT script, for example to automate unit testing.
1315
1316
1317
p. The following snippet is an example on how to retrieve all jars, including dependencies for some components from Z2:
1318
1319
1320
<pre><code class="xml"><!-- fetch all libs -->
1321
<java classpath="${z2home}/bin/z.jar"	classname="com.zfabrik.launch.MainRunner" fork="true">
1322
	<!-- general config -->
1323
	<sysproperty key="java.util.logging.config.file" 
1324
		 value="logging.properties" />
1325
	<sysproperty key="com.zfabrik.home" value="${z2home}" />
1326
	<sysproperty key="com.zfabrik.mode" value="development" />
1327
	<sysproperty key="componentName" 
1328
		 value="com.zfabrik.dev.util/jarRetriever" />
1329
	<!-- output folder -->
1330
	<arg line="-coreapi true -out ${output}" />
1331
	<!-- project to retrieve binaries from -->
1332
	<arg line="${components}" />
1333
</java></code></pre>
1334
1335
1336
p. In this example the following properties are expected:
1337
1338
| ${output}| The folder to store the retrieved jar files |
1339
| ${components}| A blank-separated list of components to retrieve the jars from |
1340
| ${z2home}| The installation folder of the Z2 home that is being used to load the jar files from |
1341
1342
1343
1344
h2. Managing z2
1345
1346
1347
p. At times it is crucial to gain insight into a running system, in particular from remote, when accessing log files or learning about the state of a process requires going through remote logins (if that is is admissible).
1348
1349
1350
p. The z2-Environment offers some basic remote management possibilities, via a simple Web interface and via Java Management Extension (JMX) exposed data and operations. For the latter, z2 comes with a simple command line interface to invoke synchronization and to access system logs.
1351
1352
1353
h3. The Basic Admin Interface
1354
1355
1356
p. As started by default, the Basic Admin Interface can be reached at the context path /adm. That is, when running remotely, it should be accessible at http://localhost:8080/adm.
1357
1358
1359
p. The browser will ask for authentication – by default configuration the username “z*” with password “z” has permission to use the interface. Please see [[#Securing z2 for Production Use|Securing z2 for Production Use]]  on how to configure security aspects for z2.
1360
1361
1362
p. The main page provides an information overview on the Java Virtual Machine Process and allows to switch between worker processes and different data sets as well as triggering some basic operations:
1363
1364
!{height:14.376cm;width:17cm;}10000201000005160000044D7CDF561F3EB49EE6.png!
1365
1366
1367
p. In particular this provides access to log content as currently written and for some time (as far as buffered by the home process) of the past:
1368
1369
!{height:7.627cm;width:17cm;}100000000000070200000325431A2E65B6F81D6B.png!
1370
1371
p. Other functions include:
1372
1373
* Checking on status of worker processes and triggering state changes
1374
* Checking on Loggers and configuring log levels (transiently)
1375
* Inspecting System Properties of the current process
1376
* Checking on Web Apps currently running and basic data such as session count and processed requests
1377
1378
1379
h3. The JMX Remoting Command Line Interface
1380
1381
1382
p. Several basic management operations of z2 are exposed via JMX MBeans and can be accessed by connecting via tools such as jconsole that is provided with the Java SDK.
1383
1384
1385
p. In order to simplify automation of management tasks, it is however simpler to use a dedicated command line tool – in particular when it comes to capabilities such as log streaming that requires some implementation logic beyond simpler attribute queries. 
1386
1387
1388
p. A few such functions are provided via the z2 command line, as built-in capabilities of the z2 launcher z.jar, that we have implicitly already see in [[#Starting and synchronizing|Starting and synchronizing]] . These functions are not implemented as embedded main programs and no repository access is required.
1389
1390
1391
p. Assuming you are in Z2_HOME/bin, running 
1392
1393
1394
<pre><code class="bash">java -cp z.jar com.zfabrik.launch.Manage -?</code></pre>
1395
1396
1397
p. will show you options of the Manage command. 
1398
1399
1400
<pre><code class="bash">SYNOPSIS 
1401
1402
java -cp z.jar Manage <command> <options> 
1403
1404
COMMANDS 
1405
    
1406
   sync        The sync performs a synchronization of a running (remote) z2 Home.   
1407
    
1408
   showlog     Continuously stream the z2 Home log of a running z2 Home to the current stderr.   
1409
1410
OPTIONS 
1411
1412
   -url <url> 
1413
       JMX URL identifying the target z2 Home. Defaults to service:jmx:rmi:///jndi/rmi://localhost:7777/jmxrmi 
1414
       The URL may be shortened to <host>:<port> (e.g. localhost:7777) 
1415
        
1416
1417
   -user <username>  
1418
    
1419
       Username used for JMX authentication. Optional. 
1420
        
1421
   -pass <password>  
1422
    
1423
       Password used for JMX authentication. Optional. Mandatory when a username has been set 
1424
        
1425
   -b <n> 
1426
    
1427
       Number of lines to read before current (if available) when running showlog.  
1428
        
1429
EXAMPLE 
1430
1431
   java -cp z.jar com.zfabrik.launch.Manage showlog -url host:7777 -user admin -pass admin </code></pre>
1432
1433
1434
p. Be aware however that connecting to JMX involves a Java Remote Method Invocation (RMI)  connection which in itself has some non-trivial aspects regarding its use of network infrastructure, as RMI may switch ports and redirects calls by using server side defined host names (which may or may not be resolvable from a client). All of these obstacles can be easily overcome – with some care. Tipps and tricks on this may be found on the Wiki at "How to Remote Manage":https://redmine.z2-environment.net/projects/z2-environment/wiki/How_to_Remote_Manage .
1435
1436
1437
h2. Enhanced Basis Features
1438
1439
1440
h3. The Binary Hub Component Repository
1441
1442
1443
p. In some cases, it is not desired to have the Z2 runtime access source code repositories directly, for example so that no source code is ever stored on production machines. Other reasons may be to remove the load of compilation from production nodes.
1444
1445
1446
p. The Hub Component repository addresses this problem by providing the following pieces:
1447
1448
* A providing side, that serves all modules and component available to the system in a pre-compiled form (as far as compilable code is involved)
1449
* A client side that connects to the providing side
1450
1451
p. So, instead of connecting to an original source of components, the Hub Component Repository enables an operational approach where some Z2 runtimes see all system content in pre-compiled form only. 
1452
1453
1454
p. Please read on at "How to use the Hub Component Repository":https://redmine.z2-environment.net/projects/z2-environment/wiki/How_to_use_the_hub_cr .
1455
1456
1457
h3. The Gateway for Zero-Downtime-Upgrades 
1458
1459
1460
p. The Gateway module implements a "zero-downtime-upgrade" feature in Z2. Specifically, it uses the worker process management of Z2 in conjunction with an intermediate reverse proxy style Web handler to implement the following feature:
1461
1462
1463
p. Upgrading a stateful Web application, i. e. a Web application that stores user data in its HTTP session typically implies downtime, and if the session state is not serializable and persisted during the upgrade, it does additionally imply that user state gets lost and typically that users need to log on again.
1464
1465
1466
p. Using the Gateway, running sessions may be preserved and worker resources may still be assigned on the current software revision for as long as there are running sessions during a node upgrade and until all sessions have been terminated. The typical application of this feature is to roll out functional and user interface corrections without interrupting users. Users can switch over to post-upgrade software by terminating their session (e. g. via a log out) and starting a new one (e. g. by logging in again).
1467
1468
1469
p. The approach behind the Gateway feature is simple:
1470
1471
* Allow separation of user sessions across worker processes
1472
* Provide an entry point to Web Applications that is capable of identifying what worker process is serving an associated session and of routing to that worker process.
1473
* Enhance worker process management with the capability of identifying stale worker processes that will not serve any user request in the future.
1474
1475
p. Please read on at "How to Gateway":https://redmine.z2-environment.net/projects/z2-environment/wiki/How_to_Gateway  to learn more about this feature.
1476
1477
1478
h2. Component type reference
1479
1480
1481
p. This section describes the component type available in a z2-base system. Add-ons may provided additional component types. For those, please visit the Z2 Wiki at 
1482
1483
1484
p. "http://redmine.z2-environment.net/projects/z2-environment/wiki":http://redmine.z2-environment.net/projects/z2-environment/wiki .
1485
1486
1487
h3. Core component properties
1488
1489
1490
p. Components in a Z2 component repository are declared using a set of properties, name-value pairs, that state the essential characteristics (beyond the name) of a component.
1491
1492
1493
p. Typically, the component type (also a property, see below) defines the set of properties that make sense declaring. Some components however look for declarations in other components. As an example visit the System State component type below.
1494
1495
1496
p. Very few properties are built-in with the z2 core and apply to any component:
1497
1498
|_. name|_. values |
1499
| com.zfabrik.component.type| The type of the component. The value of this property determines the Component Factory that implements the semantics of the component. |
1500
| com.zfabrik.component.dependencies| A comma-separated list of component names. Components listed should implement IdependencyComponent, which makes them so-called dependency components. That interface will be invoked before providing from the declaring component and the declaring component will depend on all listed components. |
1501
1502
1503
1504
p. Component dependencies allow to make sure that other components may be “prepared” before some particular component becomes used. This can be handy when some functionality of your solution depends on a side-effect established by another component. For example a web application may depend on a successful database migration check or another web application.
1505
1506
1507
p. In order to preprepared a component implementation needs to provide an implementation of I"DependencyComponent":http://www.z2-environment.net/javadoc/com.zfabrik.core.api!2Fjava/api/com/zfabrik/components/IDependencyComponent.html  to make it a dependency component, as for example Web Apps do.
1508
1509
1510
p. Note that other component types, such as [[#System States (core)|System States]]  may define properties that apply to yet other components.
1511
1512
1513
h3. “Any” components (core)
1514
1515
1516
p. Any components may represent, as the name tries to indicate any sort of interface or aspect. In short, implementations of any components simply extend the Resource Management resource base class Resource (JAVADOC) pointer.
1517
1518
1519
p. Typically, “any” components are only useful, if you need to satisfy some generic interfaces like *IDependencyComponent* but there is no more narrowly defined semantic provided in the form of a component factory. 
1520
1521
1522
p. That said, unless you have a problem that may demand an “any” component, you do not need to worry about them.
1523
1524
1525
h5. Properties of an “Any” Component:
1526
1527
|_. name|_. values |
1528
| com.zfabrik.component.type| com.zfabrik.any |
1529
| component.className| Name of the class that implements com.zfabrik.resources.provider.Resource |
1530
1531
1532
1533
h3. Component Factories (core)
1534
1535
1536
p. See [[#Components and Component Repositories|Components and Component Repositories]]  for details on the concept of component factories. 
1537
1538
1539
p. In general a component factory implementation is an implementation of the interface *com.zfabrik.components.provider.IComponentFactory*. When called, it is asked to return an extension of *com.zfabrik.resources.provider.Resource* that represents all runtime aspects of the component of the passed-on name.
1540
1541
1542
p. As a short cut, the class name given by the property *component.className *in the component's descriptor may name a class that extends *com.zfabrik.resources.provider.Resource* rather than implementing the factory interface above.
1543
1544
1545
p. In that case, the extension class must have a constructor that takes a single String parameter and it will be instantiated for a given component by its name when required (i. e. when otherwise the factory interface would have been called.
1546
1547
1548
p. Only one component factory per type name may be declared.
1549
1550
1551
h5. Properties of a Component Factory Component:
1552
1553
|_. name|_. values |
1554
| com.zfabrik.component.type| com.zfabrik.componentFactory |
1555
| component.className| Name of a class that implements  com.zfabrik.components.provider.IComponentFactory or name of a class that extends com.zfabrik.resources.provider.Resource. See also above. |
1556
| componentFactory.type| Name of the component type implemented by this factory. Components that declare to be of this type are managed by resources provided by this type. |
1557
1558
1559
1560
h3. Data Source components (z2-base)
1561
1562
1563
p. Data source components allow to manage JDBC data sources as z2 components. When present, the built-in support for JNDI lookups (see [[#Java Naming and Directory Interface (JNDI) support|Java Naming and Directory Interface (JNDI) support]]  of the z2-Environment can be used make these datasources accessible in a standard way for widely used Java frameworks such as Java persistence providers, or they may be used directly.
1564
1565
1566
p. The benefits of specifying JDBC data sources as z2 Components lies in the simple maintenance of their configuration. You are in no way limited to using this component type, when you need a datasource. At times it may be more suitable to leave your data source configuration for example in a Spring application context and expose it as a bean to make it re-usable across modules.
1567
1568
1569
p. Data source configuration is split into two parts: General configuration and Data Source implementation specific configuration.
1570
1571
1572
h5. General Properties of a Datasource Component:
1573
1574
|_. name|_. values |
1575
| com.zfabrik.component.type| javax.sql.DataSource |
1576
| ds.type| The type of data source used. Supported values are NativeDataSource or ZFabrikPoolingDataSource. See below. |
1577 8 Henning Blohm
| ds.enlist| The data source may be enlisted with the WorkUnit. Supported values are none, jta and workUnit. Default value is workUnit. See below. |
1578 7
| ds.dataSourceClass| If set, the specified data source class will be loaded as data source implementation using the private class loader of the Java module of the component holding the data source definition. When specifying this class in conjunction with the using ZFabrikPoolingDataSource as type, configuration properties will be applied to both and the pool will request new connections from the specified data source. Alternatively, the pool may be configuredto use a driver class. See below. |
1579
1580 8 Henning Blohm
1581
1582
p. The WorkUnit API provides a simple way to attach shared resources on the current thread of execution for the time of a unit of work (typically a web request, some batch job execution)  as implied by thread usage (see ApplicationThreadPool). 
1583
1584
1585
p. *If setting **ds.enlist=**workUnit** the same connection will be returned for as long as the work unit is ongoing and open. Closing the work unit** (which happens whenever the thread completes at latest)**, commits or rolls back the connection (if any) and closes it (which may mean to return it to a pool).*
1586
1587
1588
p. *When using the value **ds.enlist=***jta***, the data source is also enlisted with the workunit, but the connection is closed at after commit or rollback - that is earlier - which is often desirable. *
1589
1590
1591
p. *It is now generally recommended to use the value **jta**.*
1592 7
1593
1594
p. See also "DataSourceResource":http://www.z2-environment.net/javadoc/com.zfabrik.db.data!2Fjava/impl/com/zfabrik/impl/db/data/DataSourceResource.html .
1595
1596
1597
h4. Data Source Specific Configuration
1598
1599
1600
p. When specifying a data sourc class but also when using the built-in pooling data source, properties of the data source implementation class can be specified as Java Beans properties using the syntax below:
1601
1602
|_. ds.propType.<prop name>|_. Type of the property. Can be int, string, or boolean. Default value is string.  |
1603
| ds.prop.<prop name>| Value of the data source property to be set according to its type setting above.  |
1604
1605
1606
1607
h4. Data Source Types
1608
1609
1610
p. Currently the Data Source support allows to specify two different types of data sources: 
1611
1612
1613
h5. NativeDataSource
1614
1615
1616
p. When declaring a native data source, the ds.dataSourceClass must be specified to name a data source implementation class. 
1617
1618
1619
p. All further configuration of the data source is done generically using the property scheme below,
1620
1621
1622
h5. ZFabrikPoolingDataSource
1623
1624
1625
p. When declaring a ZFabrikPoolingDataSource a z2 provided data base connection pool implementation will be used that has the following configuration properties:
1626
1627
| Name | Type| Value |
1628
| driverClass| string| Name of the actual JDBC Driver implementation class. E.g. com.mysql.jdbc.Driver for MySQL. |
1629
| url| string| JDBC connection url |
1630
| user| string| User name for authentication at the data base. |
1631
| password| string| Password for authentication at the data base. |
1632
| maxInUseConnections| int| Maximal number of connections handed out by this pool. This number may be used to limit database concurrency for applications. Requesting threads are forced to wait for freed connections if this limit has been exhausted. Make sure threads are not synchronized on shared resources when requesting connections and when this limit is less than your theoretical application concurrency as this may lead to thread starvation. |
1633
| maxSpareConnections| int| Number of connection held although not currently used by the applications. |
1634
| connectionExpiration| int| Connections will be closed after this number of milliseconds has expired since creation and when returned to the pool. This setting can be used to make sure stale connections get evicted although not detected otherwise by the pool. |
1635
| connectionMaxUse| int| Connections will be closed after this number of times they have been handed out from the pool and when returned to the pool. This setting can be used to make sure connections only serve a limited number of requests. |
1636
1637
1638
1639
p. See also "PoolingDataSource":http://www.z2-environment.net/javadoc/com.zfabrik.db.data!2Fjava/impl/com/zfabrik/impl/db/data/PoolingDataSource.html .
1640
1641
1642
1643
p. A typical ZFabrikPoolingDataSource configuration looks like this:
1644
1645
1646
<pre><code class="bash">#
1647
# MySQL driver configuration
1648
#
1649
ds.dataSourceClass=com.mysql.jdbc.jdbc2.optional.MysqlDataSource
1650
ds.prop.user=z2
1651
ds.prop.password=z2
1652
ds.prop.url=jdbc:mysql://localhost:3306/z2_samples?autoReconnect=true
1653
#
1654
# Generic pooling config
1655
#
1656
ds.prop.maxInUseConnections=10
1657
ds.propType.maxInUseConnections=int
1658
ds.prop.maxSpareConnections=5
1659
ds.propType.maxSpareConnections=int
1660
ds.prop.connectionExpiration=60000
1661
ds.propType.connectionExpiration=int</code></pre>
1662
1663
1664
h3. File system component repositories (core)
1665
1666
1667
p. File system based repositories are the most straightforward repositories. All that is required is a file system folder that holds components and component resources in a structure as described in [[#Components and Component Repositories|Components and Component Repositories]] . As always for component repositories, it is important to make sure they are started early on in the life-cylce of a z2 runtime.
1668
1669
1670
p. Note that unlike the development repository (see [[#Developing with the z2-Environment|Developing with the z2-Environment]] ), the file system repository is not robust under modifications: Resources in the folder structure of the file system repository will be accessed at any time the z2 runtime requires to – which may be significantly later than the latest synchronization that decided about invalidations due to changes. Resources should not be modified in the meantime to assure consistency.
1671
1672
1673
h5. Properties of a File System Component Repository Component:
1674
1675
|_. name|_. values |
1676
| com.zfabrik.component.type| com.zfabrik.fscr |
1677
| fscr.folder| Store folder, i.e. the file system folder that holds the actual resources of the repository. |
1678
| fscr.base| If the value of fscr.folder is not an absolute file system path but a relative path instead, this setting specifies what it is evaluated in relation to. Allowed values are “home” (default) and “here”.If set to “home”, the basis of evaluation is the z2 Home folder (see [[#Folder Structure of a Z2 Home|#FolderStructureOfHome]] ).If set to “here”, the basis of evaluation is the resource folder of the declaring component. This is useful, if you want to declare FS component repositories from FS component repositories in a relative fashion. |
1679
| fscr.checkDepth| Component folder traversal depth when determining the latest time stamp. Set to less than zero for infinite depth. Default is -1. |
1680
| fscr.priority| Component repository priority. See IComponentsRepository. Default is 250. |
1681
1682
1683
h3. GIT component repositories (core)
1684
1685
1686
p. When using a Git based component repository, the z2 runtime manages a local clone of another Git repository. This allows to declare Git component repositories that refer to a local Git repository, typically present in a development setup, or to remote Git repositories, used for production setups.
1687
1688
1689
p. In both cases, when synchronizing, the component repository will pull updates from the configured repository and check for modifications by inspecting the local workspace, i.e. the Git workspace maintained by the z2 environment runtime itself. 
1690
1691
1692
p. Note: When specifying a local repository in gitcr.uri the relevant branch is still the one configured in the component properties (see below), not the checked out branch of the local repository. 
1693
1694
1695
p. By default, the root of the repository is considered the root of the component repository as well. That is, modules would be identified as direct sub folder of the Git repository root path.
1696
1697
1698
p. A Git component repository may be configured to use other locations inside the repository instead using the *gitcr.roots* configuration property. Instead of checking for modules at the root of the Git repository, modules will be searched at the given relative paths in the repository. For example, given  *gitcr.**roots**=repo1,other/repo2* the relatives paths *repo1* and *other/repo2* will be searched.
1699
1700
1701
p. The order of paths in the comma-separated list determines the priority in overlaying in decreasing order. That is, using the example above, if a module *myModule* would be found at *repo1/myModule* as well as in *other/repo2/myModule*, the latter definition would be ignored.
1702
1703
1704
p. The Git component repository allows flexibility in describing the content version to be considered by allowing any reference that is meaningful in the source repository. The reference will be used in a fetch specification so that partial cloning is supported. The reference specified does not need to be a branch or tag but can be, in particular, HEAD, which can be particularly useful for feature branch development as that allows simple switching of branches without configuration changes in z2.
1705
1706
1707
p. See also [[#Git support|Git support]]  for more information on Git support.
1708
1709
1710
h5. Properties of a Git Component Repository Component:
1711
1712
|_. name|_. values |
1713
| com.zfabrik.component.type| com.zfabrik.gitcr |
1714
| gitcr.uri| The URI to the Git repository to clone from. This can be an absolute path, a local path relative to .../bin, or a remote URL. See the Git documentation for examples. |
1715
| gitcr.priority| The priority of the repository. Defaults to 500. |
1716
| gitcr.ref| A ref to check out as active content. This can be * a tag (refs/tags/<tag name>), 
1717
* a branch (refs/heads/<branch name>
1718
* HEAD for the default branch (i.e. where HEAD points to)
1719
In practice this can be anything used for the JGit check out command (omitting the branch creation part) which is very similar to what may be used in the git checkout command (omitting anything beyond checkout, such as branch creation).Use this option, if you need more control then given by gitcr.branch). Note that the latter will be used with preference and hence needs to be omitted, if you want to use gitcr.ref.Note: The Git Component Repository uses this reference to fetch from remote – that is, the reference must be anything that is meaningful at the source Git repository.  |
1720
| gitcr.branch| The branch to checkout. Setting this is equivalent to setting a gitcr.ref value  refs/remotes/origin/<branch name> and will be considered with preference over gitcr.ref. |
1721
| gitcr.roots| A comma-separated list of repository local paths that serve as roots of the actual component repository content. The order is in decreasing priority. See also above. Defaults to the empty path which identifies the root of the repository. |
1722
1723
1724
1725
h3. Java components (core)
1726
1727
1728
p. Java components are among the very few very essential component types already defined in the Z2 core. The knowledge about Java components is essential to the environment so it can bootstrap.
1729
1730
1731
p. The Java component implementation takes care of the following tasks:
1732
1733
* Resolving includes for assembly 
1734
* Resolving references of Java components for class path computation and class loader management 
1735
* Triggering (re-) compilation of source code in a Java component using the compiler API
1736
1737
p. The mechanisms around references and includes between Java components and the separation of Java components into public (api), private (impl), and test, are the underpinnings of the software modularization features of z2, which is why we discuss these in some depth here.
1738
1739
1740
h4. Classloaders
1741
1742
1743
p. The class loader concept of the Java platform provides a powerful name spacing mechanism on the type system. While in the beginning that seems to be of little concern, in more complex scenarios isolation within the type system in conjunction of sharing of types between modules of a solution becomes the catalyst of successful modularization.
1744
1745
1746
p. Isolation means that modules on the platform may use types without sharing them, that is without making them visible to other modules. That can be important for various reasons:
1747
1748
* Implementation types should be hidden from potential users so that modifications do not break using modules.(encapsulation).
1749
* In particular third party libraries used in the implementation of a module may conflict with other versions of similar libraries so that exposing them would lead to unnecessary risks on the consuming side (multiple versions)
1750
1751
p. Sharing of types on the other hand allows to refer to the very same types from different modules and, as they are shared, provides an efficient type safe way of communicating state between modules:
1752
1753
* By publishing an API, modules may expose services efficiently to other modules
1754
1755
1756
p. Based on these mechanisms, modularization for Java components on Z2 provides the ability to maintain a system of named modules that have defined contracts among each other while still maintaining local integrity and cohesion. 
1757
1758
1759
p. The class loading system in Z2 is based on a ancestry-first, multi-ancestor scheme. Effectively, a Java component will have two class loaders at runtime. One for the API, one for the Implementation and both ask their ancestors (other class loaders) first before searching local resources.
1760
1761
1762
p. The API class loader will have ancestors corresponding to all Java components identified by the public references. The implementation class loader will have the API class loader as ancestor and  ancestors corresponding to all Java components identified by the private references of the Java component (see below).
1763
1764
1765
h4. Includes
1766
1767
1768
p. Another important mechanism supported by the Z2 Environment is so called “Java includes”. The references feature described above allows sharing of types and class path resources without duplicating them at runtime. 
1769
1770
1771
p. There are cases however where duplication of types is necessary – although that is fortunately the exception:
1772
1773
* Frameworks like the Spring Framework supply pre-compiled libraries that contain “adapters” for various other frameworks that may not be present on the using application. The late linking qualities of the Java VM supports unresolvable type references as long as they are not needed. In this case, the library must be used in the class loading name space of the using application to make sure it gets appropriate type visibility.
1774
* Some libraries attach information about the using application to the class loading namespace itself, e.g. via class variables. In that case, sharing types can easily lead to unpredictable behavior as state from different class loading name spaces may override each other.
1775
1776
p. The use of includes, actually in most cases only “private includes” implements exactly that. The Java resources of the included component get copied into the using Java component and hence are used as if provided by the using Java component. 
1777
1778
1779
p. The picture below shows a simplified example overview over the reference and the include mechanisms:
1780
1781
1782
!{height:11.192cm;width:16.365cm;}1000020100000628000004361E3526C0E2036BF0.png!
1783
1784
1785
h5. Properties of a Java Component:
1786
1787
|_. name|_. values |
1788
| com.zfabrik.component.type| com.zfabrik.java |
1789
| java.publicReferences| Points to another java component whose public types will be shared with this one (and maybe others). Everything referenced as public reference will be visible to the public interface of the referencing component as well as to all referencing the referencing component. In other words: References are transitive. In particular, anything required to compile the public types of a Java component must be referenced via this reference property. Components may be specified as a comma-separated list. Component names that have no "/" will be defaulted by appending "/java". |
1790
| java.publicIncludes| Points to com.zfabrik.files or com.zfabrik.java components that must have a bin (or alternatively a bin.api, for Java components) folder that will be included into this java component's public java  resources. The component may also have a src (or alternatively src.api, for Java components) folder that will be copied before compilation into src.api. |
1791
| java.publicClassPathInclusion| Custom regular expression for classpath computation of the public classloader. Only library files matching the specified pattern will be included into the respective classpath computation. This has no effect on the inclusion of .class files. Defaults to “^.*(?<!-sources)\\.jar$” (i.e. including all jar files except those ending on “-sources” before the file extension). |
1792
| java.publicCompile.order| Like java.compile.order below, but only applying to the public resources and considered with preference. |
1793
| java.privateReferences| Points to another java component whose public types will be shared with this one (and maybe others) Nothing referenced as private reference will be automatically exposed to the public interface  of the referencing component nor to other components. Anything needed to compile the private types of a Java component, must be referenced as a public reference, be part of the public types of  that component, or be referenced via this reference property. In other words: The private types automatically see the public types and transitively anything referenced publicly as described above. In addition, to use more types in the "private implementation section" of a Java component, types that will not be exposed to referencing components, use this reference property. Components may be specified as a comma-separated list. Component names that have no "/" will be defaulted by appending "/java". |
1794
| java.privateIncludes| Points to com.zfabrik.files or com.zfabrik.java components that must have a bin (or alternatively a bin.api, for Java components) folder that will be included into this java component's private java resources. The component may also have a src (or alternatively src.api, for Java components) folder that will be copied before compilation into src.impl. |
1795
| java.privateClassPathInclusion| Custom regular expression for classpath computation of the private classloader. Only library files matching the specified pattern will be included into the respective classpath computation. This has no effect on the inclusion of .class files. Defaults to “^.*(?<!-sources)\\.jar$” (i.e. including all jar files except those ending on “-sources” before the file extension). |
1796
| java.privateCompile.order| Like java.compile.order below, but only applying to the private resources and considered with preference. |
1797
| java.testReferences| Points to another java component whose public types will be shared with this one (and maybe others) if the execution mode, as defined by the system property (see Foundation.MODE} is set  to development. Test references extend the private references. In conjunction with the tests source folder this allows to add test code and corresponding dependencies that will be ignored by the  runtime unless running in development mode. |
1798
| java.testIncludes| Points to com.zfabrik.files or com.zfabrik.java components that must have a bin (or alternatively a bin.api, for Java components) folder that will be included into this java component's test java  resources. The component may also have a src (or alternatively src.api, for Java components) folder that will be copied before compilation into src.test. |
1799
| java.testClassPathInclusion| Custom regular expression for classpath computation of the test classpath. Only library files matching the specified pattern will be included into the classpath computation. This has no effect on the inclusion of .class files. Defaults to “^.*(?<!-sources)\\.jar$” (i.e. including all jar files except those ending on “-sources” before the file extension). |
1800
| java.testCompile.order| Like java.compile.order below, but only applying to the test resources and considered with preference. |
1801
| java.compile.order| The compile order must be defined in java components that also contain non-java sources - e.g. scala. This property can be omitted for pure java components, otherwise one has to define all  compilers in the right order - e.g: scala, java |
1802
1803
1804
1805
h3. JUL configurations (z2-base)
1806
1807
1808
p. The standard logging implementation contained in the package java.util.logging (or JUL for short) of the Java SE distribution can be configured using components of type java.util.logging.
1809
1810
1811
p. The z2 Environment implementation uses JUL throughout (rather than log4j or other logging mechanisms). Defining java.util.logging components provides an easy way to distribute log configurations without the need to modify command lines and without need to restart the runtime,
1812
1813
1814
p. Components of type java.util.logging are expected to provide a file called *logging.properties* in their resources (see for example the component *environment/logging* in z2_base/base). That file will be applied using *LogManager.getLogManager().readConfiguration(...)* every time the component is prepared (as in *IDependencyComponent*, i.e. as part of a dependency resolution), e.g. when (re-) attaining a participated system state.
1815
1816
1817
h5. Properties of a JUL Configuration Component:
1818
1819
|_. name|_. values |
1820
| com.zfabrik.component.type| java.util.logging |
1821
1822
1823
1824
h3. Link Components
1825
1826
1827
p. Link components can be used to re-use existing component declarations and resources by another module and component name. Details are explained in [[#Link Components and Component Linking|Link Components and Component Linking]] .
1828
1829
1830
p. Link components are declard using the component type *com.zfabrik.link*.
1831
1832
1833
h5. Properties of a Link Component:
1834
1835
|_. name|_. values |
1836
| link.targetComponent| Name of the target component.  |
1837
1838
1839
1840
h3. Log4J configurations (z2-base)
1841
1842
1843
p. Components of type *org.apache.log4j.configuration* are handled exactly as components of type *java.util.logging* (see right above), except that a file called *log4j.properties* is expected and loaded using Log4J's *PropertyConfigurator* API (see the Log4J documentation for the specifics of Log4J  configuration).
1844
1845
1846
h5. Properties of a Log4J Configuration Component:
1847
1848
|_. name|_. values |
1849
| com.zfabrik.component.type| org.apache.log4j.configuration |
1850
1851
1852
1853
h3. Main Program Components (core)
1854
1855
1856
p. While the z2-environment has built-in support for long running worker processes it is perfectly usable to run command line programs via the Main Runner as described in section [[#The z2 Command Line, the Embedded Runtime and the Main Runner|#embedded]] .
1857
1858
1859
p. In order to implement a Main Program component to be called from the command line, the component implementation is required to either
1860
1861
* support lookup as java.lang.Class returning a class object that has a main method,
1862
* or make use of the component type com.zfabrik.mainProgram and declare an implementation class that has a main method.
1863
1864
p. Note: A main method, is a method of the signature
1865
1866
1867
<pre><code class="java">public static void main(String[] args)</code></pre>
1868
1869
1870
p. In the first case, the declared component type is irrelevant, as long as a lookup requirement is satisfied. For example an “any” component serving as a Main Program could be implemented like this:
1871
1872
1873
<pre><code class="java">public class MainResource extends Resource {
1874
1875
	@Override
1876
	public <T> T as(Class<T> clz) {
1877
		if (clz.equals(Class.class)) {
1878
			return clz.cast(MainResource.class);
1879
		}
1880
		return super.as(clz);
1881
	}
1882
1883
	public static void main(String[] args) {
1884
		System.err.println("hello");
1885
	}
1886
}</code></pre>
1887
1888
1889
p.  In the second case, it is not required to implement a typed lookup implementation via the as(..) method. Instead a class with a main method suffices.
1890
1891
1892
p. Example:
1893
1894
1895
p. Component declaration:
1896
1897
1898
<pre><code class="java">com.zfabrik.component.type=com.zfabrik.mainProgram
1899
component.className=test.Main</code></pre>
1900
1901
1902
p. Main class implementation:
1903
1904
1905
<pre><code class="java">public class Main {
1906
	public static void main(String[] args) {
1907
		System.err.println("Hello Main");
1908
	}
1909
}</code></pre>
1910
1911
1912
p. Assuming the component is declares as mymodule/main, the environment variable Z2_HOME is set, the command line
1913
1914
1915
<pre><code class="bash">java -DcomponentName=mymodule/main -cp z.jar com.zfabrik.launch.MainRunner</code></pre>
1916
1917
1918
p. will invoke the main program (note: for experimentation you might want to work with a locally defined development state using the dev repo. In that case set the system property  *com.zfabrik.dev.local.workspace* on the command line accordingly - e.g. to the folder above your development modules  - see also [[#Workspace development using the Dev Repository |#devRepo]] ).
1919
1920
1921
p. All shared component properties, such as those declaring dependencies, are supported. A main program runs in exactly the same context as any other component defined. This make Main Program components an extremely useful command line interface of a potentially application system.
1922
1923
1924
1925
h5. Properties of a Main Program Component:
1926
1927
|_. name|_. values |
1928
| com.zfabrik.component.type| com.zfabrik.mainProgram |
1929
| component.className| Name of class that has a main method. |
1930
1931
1932
1933
h3. Maven component repositories (z2-base)
1934
1935
1936
p. Maven component repositories allow to integrate artifacts from Maven artifact repositories without copying them into your system. See [[#Maven Repository Support|Maven Repository Support]]  for more details.
1937
1938
1939
h5. Properties of a Maven Component Repository Component:
1940
1941
|_. name|_. values |
1942
| com.zfabrik.component.type| com.zfabrik.mvncr |
1943
| mvncr.settings | Specifies the location of the settings XML file relative to the components resources. This is expected to be a standard Maven configuration file. Defaults to settings.xml |
1944
| mvncr.roots| A comman-separated list of root artifacts |
1945
| mvncr.managed| Fixed artifact versions, if encountered during recursive root resolution. This corresponds to a <dependencyManagement> section in a Maven POM file. |
1946
| mvncr.excluded | A comma separated list of artifacts that will be skipped during resolution of any root  |
1947
| mvncr.priority | Component repository priority. See IComponentsRepository. Default is 500. |
1948
| mvncr.repository| Symbolic name of the repository. Use this to define a component name independent identifier for the repository that fragments (see below) can reference.  |
1949
1950
1951
1952
1953
p. In order to deviate from the default resolution and mapping, maven repository roots may be specified with a query string syntax like this:
1954
1955
1956
1957
<pre><code class="bash">org.springframework.security:spring-security-aspects:3.2.2.RELEASE?versioned=true&scope=RUNTIME&excluded=commons-logging:commons-logging:1.1.2</code></pre>
1958
1959
1960
p. Admissable query parameters are
1961
1962
1963
|_. param|_. meaning |
1964
| com.zfabrik.component.type| com.zfabrik.mvncr |
1965
| 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. |
1966
| 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. |
1967
| excluded | Exclusions on the dependency graph.  |
1968
1969
1970
h3. Maven component repository fragments (z2-base)
1971
1972
1973
p. A Maven component repository fragment allows to add dependency graph information to a Maven component repository (see above).
1974
1975
1976
h5. Properties of a Maven Component Repository Fragment Component:
1977
1978
|_. name|_. values |
1979
| com.zfabrik.component.type| com.zfabrik.mvncr.fragment |
1980
| mvncr.component| The component name (or a comma-separated list of component names) of  Maven component repository or Maven component repository fragment declarations this fragment adds to. DEPRECATED, use mvncr.repository instead. |
1981
| mvncr.repository| The maven repository name (or a comma-separated list of repository names) of  Maven component repository or Maven component repository fragment declarations this fragment adds to. |
1982
| mvncr.roots| As above. Will be merged with the repo this fragment adds to. |
1983
| mvncr.managed| As above. Will be merged with the repo this fragment adds to. |
1984
| mvncr.excluded | As above. Will be merged with the repo this fragment adds to. |
1985
1986
1987
1988
h3. Subversion component repositories (core)
1989
1990
1991
p. Subversion component repositories provide an easy and robust way to run z2 in a highly controlled and versioned yet scalable way. 
1992
1993
1994
p. See [[#Components and Component Repositories|Components and Component Repositories]]  for details on Subversion support.
1995
1996
1997
h5. Properties of a Subversion Component Repository Component:
1998
1999
|_. name|_. values |
2000
| com.zfabrik.component.type| com.zfabrik.svncr |
2001
| svncr.url| URL of the subversion root folder of the repository. E.g. something like svn://z2-environment.net/z2_base/trunk/base |
2002
| svncr.user| User name for Subversion authentication (optional). |
2003
| svncr.password| Password for Subversion authentication (optional) |
2004
| svncr.priority| Component repository priority. See IComponentsRepository. Default is 500. |
2005
2006
2007
2008
p. By default, a Subversion component repository needs to be able to connect to the Subversion repository. In most cases this means that you need to be online when running a z2 environment, even when developing.
2009
2010
2011
p. In reality however, the repository has all required resources in its local caches and only checks for updates. In development situations it can be very handy to have the repository simply go by what is on the caches and continue developing in an Eclipse workspace gladly ignoring possible central modifications.
2012
2013
2014
p. To enable that you can set the system property 
2015
2016
2017
<pre><code class="bash">-Dcom.zfabrik.repo.mode=relaxed </code></pre>
2018
2019
2020
p. in *launch.properties** **(see also *[[#Important System Properties|*#systemProps*]] ). In that case, failing to connect to a remote repository will be noted by a warning but otherwise ignored and the repository will try to satisfy component lookups from cached data.
2021
2022
2023
p. To avoid problematic licenses, the z2 Environment does unfurtunately not come with complete built-in Subversion connectivity. Additional configuration steps are required once to complete subservion enabling on your side, as described in the "Subversion How-To":https://redmine.z2-environment.net/projects/z2-environment/wiki/How_to_Subversion .
2024
2025
2026
h3. System States (core)
2027
2028
2029
p. System states are abstract target configurations for z2 processes. Systems can easily develop into a non-trivial set of web applications, batch jobs, web service interfaces and more that interplay with each other to implement solution scenarios. Take for example an e-commerce web site: There is the actual shop front-end but also report generation, mass-emailing, shop content administration, etc.
2030
2031
2032
p. It is handy to group components that form parts of an overall scenario and that need to be initialized beforehand, such as web applications, or update scheduling for analytical data aggregation.
2033
2034
2035
p. System states support dependency declarations in two directions:
2036
2037
* Via the property com.zfabrik.systemStates.dependencies a comma-separated list of components that this state depends on and that must be prepared to have the state attained.
2038
* Via the property com.zfabrik.systemStates.participation a comma-separated list of other system state components may be specified that are to depend on this system state and that cannot be attained unless this system state has been prepared (which equals attained in this case). This property may be declared on components of any type.
2039
2040
p. State dependencies are evaluated in an eager way. That is, even if some dependency fails to prepare,  and eventually the system state will not be attain, all other dependencies will still try to be prepared.
2041
2042
2043
p. System state dependencies are similar to component dependencies (see [[#Core component properties|Core component properties]] ). There are subtle differences however in that component dependencies are evaluated much earlier in the life cycle of a component than state dependencies. In essence that means, that the system state implementation may never evaluate participations if its component dependencies fail. 
2044
2045
2046
p. Also, any preparation of a system state, for example during the verification step of a synchronization, will trigger a preparation of all dependent dependency components (unlike a component dependency, that will only be prepared again, if invalidated).
2047
2048
2049
p. Hence, on system states, it is preferable to not use component dependencies but rather the declarations above.
2050
2051
2052
p. In practice, system states serve as a convenient, named place holder for parts of an overall scenario.
2053
2054
2055
p. Attaining a system state means to “prepare” (see "IDependencyComponent":http://www.z2-environment.net/javadoc/com.zfabrik.core.api!2Fjava/api/com/zfabrik/components/IDependencyComponent.html ) all dependent component and do so again if one got invalidated and the system is to be attained again.
2056
2057
2058
p. The system state feature is used by z2 in several places:
2059
2060
* All z2 processes (in server mode) have the target state com.zfabrik.boot.main/process_up
2061
* The home process has a hard-coded target state com.zfabrik.boot.main/home_up
2062
* Worker processes always have the target state com.zfabrik.boot.main/worker_up
2063
* Component repositories should participate in com.zfabrik.boot.main/sysrepo_up
2064
* Worker processes express their target configuration by a list of system states to attain (and keep attained). See below for worker process component configuration.
2065
2066
p. As mentioned above, in order to assign components as part of a system state, you can either list them as dependency components in the system state definition like this:
2067
2068
2069
<pre><code class="bash">com.zfabrik.systemStates.dependencies=\
2070
	mymodule1/comp1,\
2071
	mymodule2/comp2</code></pre>
2072
2073
2074
p. Or, in the case of other system states, mark them as participants of the system state. For example to your component's properties you could add
2075
2076
2077
<pre><code class="bash">com.zfabrik.systemStates.participation=com.zfabrik.boot.main/worker_up</code></pre>
2078
2079
2080
p. By convention, the most essential system states used and participated in for application components are declared in the “environment” module. We suggest to use:
2081
2082
* environment/webWorkerUp for web interfaces
2083
* environment/jobWorkerUp for asynchronous data processing.
2084
2085
p. Larger scenarios may need more fine-grained scenario partitioning.
2086
2087
2088
p. Declaring a system state requires no more that declaring a component of the corresponing type.
2089
2090
2091
h5. Properties of a System State Component:
2092
2093
|_. name|_. values |
2094
| com.zfabrik.component.type| com.zfabrik.systemState |
2095
| com.zfabrik.systemStates.dependencies| A comma-separated list of components that this state depends on and that must be prepared to have the state attained. |
2096
2097
2098
2099
p. The following diagram shows typical system state relationships in a worker process:
2100
2101
!{height:12.485cm;width:13.831cm;}1000020100000441000003D7FD54F9BEE0DA91D7.png!
2102
2103
2104
h3. Web applications (z2-base)
2105
2106
2107
p. Web application configuration is split into three parts: 
2108
2109
# The Java EE standard Web application deployment descriptor found at WEB-INF/web.xml the Web application's Web resources.
2110
# Container-specific extended Web application configuration. In the case of Jetty (currently the default Web container in z2) please check out the documentation on Jetty's WEB-INF/jetty-web.xml configuration file.
2111
# The z2 component descriptor that covers the remaining parts (such as the Web app's context path) and life cycle control inherent to z2.
2112
2113
2114
p. Web applications have the following module structure in z2:
2115
2116
| WebContent| Folder holding the standard Java Web application structure, such as the WEB-INF folder. |
2117
| z.properties| Component descriptor of the Web application |
2118
2119
2120
2121
h5. Properties of a Web Application Component:
2122
2123
|_. name|_. values |
2124
| com.zfabrik.component.type| com.zfabrik.ee.webapp |
2125
| webapp.path| Context path of the web application. |
2126
| webapp.server| Component name of the web server to host this Web application. |
2127
| webapp.requiredPaths| A comma-separated list of context paths this Web application relies on. This is an alternative way of defining a component dependency by Web app context path rather than by component name. |
2128
| webapp.ContainerIncludeJarPattern| The jars that qualify for meta-data parsing can be limited in Jetty. In z2 the default is defined by the regular expression "(?!.+-sources\\.).*\\.jar$" (as Java string) which is all Jars except the source code jars (by convention).  See also "the Jetty Documentation":http://www.eclipse.org/jetty/documentation/9.1.1.v20140108/configuring-webapps.html#container-include-jar-pattern . |
2129
2130
2131
2132
h3. Web servers (z2-base)
2133
2134
2135
p. In order to run Web Applications, arguably the most prominent reason to run an application server, z2 integrates the Jetty Web Container. 
2136
2137
2138
p. There is no particular reason other than that Jetty is a well-embeddable, well performing, standard compliant web container. Based on z2's extensible component model, the way Jetty has been integrated, Tomcat could be integrated as well. Contact us, if that is important for you.
2139
2140
2141
p. The component type *com.zfabrik.ee.webcontainer.jetty* configures instances of Jetty web servers. While in most cases you will not operate more than one, the component still provides the place to hold Jetty configuration. As an example have a look at the *environment/webServer* component in z2_base/base.
2142
2143
2144
h5. Properties of a Web Server Component:
2145
2146
|_. name|_. values |
2147
| com.zfabrik.component.type| com.zfabrik.ee.webcontainer.jetty |
2148
| jetty.config| Names a Jetty configuration file (typically called jetty.xml) relative to the component's resource folder |
2149
| jetty.override-web.xml| Names a override web.xml file, that can be used to override web application configurations for all web applications. The file name is considered relative to the component's resource folder |
2150
| jetty.default-web.xml| Names a default web.xml file, that defines web application defaults for all web applications. The file name is considered relative to the component's resource folder |
2151
2152
2153
2154
h3. Worker Processes (z2-base)
2155
2156
2157
p. Worker processes are managed by the home process when running in server mode. Worker processes improve robustness of the z2 runtime as applications running in some worker process do not impact applications running in another worker process nor and in particular, do crashing worker processes impact the home process. 
2158
2159
2160
p. See [[#Installing and Understanding a Z2 Home|Installing and Understanding a Z2 Home]]  for more information on how a z2 home works.
2161
2162
2163
h5. Properties of a Worker Processes Component:
2164
2165
| name| values |
2166
| com.zfabrik.component.type| com.zfabrik.worker |
2167
| worker.process.vmOptions| General virtual machine parameters for the worker process. See the JVM documentation for details. See below for consideration on command line syntax. |
2168
| worker.process.vmOptions.<os name>| Override of the general VM options above for a specific operating system. Use the OS name returned by the RuntimeMXBean to replace <os name> with. See below for consideration on command line syntax. |
2169
| worker.states| Comma-separated list of target state (components) of the worker process (see also ISystemState). The worker process, when starting, will try to attain these target states and will try so again during each verification and synchronization.  |
2170
| worker.concurrency| Size of application thread pool (see ApplicationThreadPool). In general this thread pool is used for application type work (e.g. for web requests or parallel execution within the application). This property helps achieving a simple but effective concurrent load control  |
2171
| worker.process.timeouts.start| Timeout in milliseconds. This time out determines when the worker process implementation will forcibly kill the worker process if it has not reported startup completion until then.  |
2172
| worker.process.timeouts.termination | Timeout in milliseconds. This time out determines when the worker process implementation will forcibly kill the worker process if it has not terminated after this timeout has passed since it was asked to terminate.  |
2173
| worker.process.timeouts.communication| Timeout in milliseconds. This time out is the default timeout that determines the time passed after which the worker process implementation will forcibly kill a worker process if a message request has not returned.  |
2174
| worker.debug| Debugging for the worker process will be configured if this property is set to true and the home process has debugging enabled. Otherwise the worker process will not be configured for debugging.  |
2175
| worker.debug.port | The debug port to use for this worker process, if it is configured for debugging. |
2176
| worker.inheritedSystemProperties| Some system properties set on the z2 home process via the command line (or launch.properties) are useful to be propagated to worker processes. This property can be used to specify a comma-separated list of such properties. See below for more details. |
2177
2178
2179
2180
h4. System Property Propagation from Home to Worker Process
2181
2182
2183
p. Some system properties set on the z2 home process via the command line (or launch.properties) are useful to be propagated to worker processes. The property *worker.inheritedSystemProperties *can be used on worker process declaration to specify a comma-separated list of such properties. See below for more details.
2184
2185
2186
p. Note that all properties set in runtime.properties (see [[#Using the Offline Mode|#offlineMode]] ) will be set on all z2 processes regardless. If however properties may be set depending on some starting command line, it can be useful to have them propagated as is.
2187
2188
2189
p. By default, the following system properties will be propagated via the command line from the home process to the worker process by default:
2190
2191
2192
| Property| Meaning |
2193
| com.sun.management.config.file| JMX config file. Preferrably preserve. |
2194
| com.zfabrik.config| Name of config file. Defaults to runtime.properties. See [[#Important System Properties|#systemProps]] . |
2195
| java.util.logging.config.file| Default Java logging configuration. |
2196
| com.zfabrik.dev.local.workspace| Setting of the development repository defining where to check for “armed” modules. See also [[#Important System Properties|#systemProps]]  and in particular [[#Workspace development using the Dev Repository |#devRepo]] . |
2197
| com.zfabrik.dev.local.repo| (outdated) |
2198
| com.zfabrik.repo.mode| General repository access mode. If set to “relaxed”, repositories will attempt to work on previously cached resources in case of technical repository access failures during synchronization. If set to “strict” (which is the default), technical failures will lead to a failure in synchronization, even if local resources are available. This feature is useful for offline or bad connectivity situations.  |
2199
| java.library.path| See Java documentation. |
2200
| com.zfabrik.mode| For development mode. See [[#Important System Properties|#systemProps]]  |
2201
| com.zfabrik.proxy.auth
2202
https.proxyPort
2203
https.proxyHost
2204
http.proxyPort
2205
http.proxyHost
2206
proxyPort
2207
proxyHost
2208
proxyUser
2209
proxyPassword| Proxy configuration. See "https://redmine.z2-environment.net/projects/z2-environment/wiki/How_to_prox":https://redmine.z2-environment.net/projects/z2-environment/wiki/How_to_proxy_settings "y_settings":https://redmine.z2-environment.net/projects/z2-environment/wiki/How_to_proxy_settings . |
2210
2211
2212
2213
p. That is, the default value of *worker.inheritedSystemProperties* is:
2214
2215
2216
<pre><code class="bash">worker.inheritedSystemProperties=com.sun.management.config.file,\
2217
  com.zfabrik.config,\
2218
  java.util.logging.config.file,\
2219
  com.zfabrik.dev.local.workspace,\
2220
  com.zfabrik.dev.local.repo,\
2221
  com.zfabrik.repo.mode,\
2222
  com.zfabrik.proxy.auth,\
2223
  java.library.path,\
2224
  com.zfabrik.mode,\
2225
  https.proxyPort,\
2226
  https.proxyHost,\
2227
  http.proxyPort,\
2228
  http.proxyHost,\
2229
  proxyPort,\
2230
  proxyHost,\
2231
  proxyUser,\
2232
  proxyPassword</code></pre>
2233
2234
2235
h4. Special considerations when specifying VM options using blanks and quotes
2236
2237
2238
p. Virtual machine options specified using the component property *worker.process.vmOptions* or its OS specific variant will be parsed by Z2 and conveyed as command line arguments to the child process. In general, the specified command line will be broken up at blank characters (multiple in a sequence counting as one). 
2239
2240
2241
p. Special considerations apply when there is a need to define virtual machine options containing blanks or double quotes: Any text enclosed in double quotes will be treated as one “token” when breaking up command line options. That is, in order to supply an option that contains blanks, put it in double quotes. 
2242
2243
2244
p. *For example*
2245
2246
2247
<pre><code class="bash">worker.process.vmOptions=-Dprop1=A -Dprop2=it works</code></pre>
2248
2249
2250
p. will lead to system properties prop1=”A” and prop2=”it” and some probably problematic option “works”. In order to achieve the desired prop2=”it works”, use 
2251
2252
2253
<pre><code class="bash">worker.process.vmOptions=-Dprop1=A “-Dprop2=it works”</code></pre>
2254
2255
2256
p. Finally, if you need to convey double quotes in VM options, use the backslash (“\”) escape to escape quotes. The latter  works in quoted text only.
2257
2258
2259
p. For example
2260
2261
2262
<pre><code class="bash">worker.process.vmOptions=-Dprop1=A “-Dprop2=it \”works\””</code></pre>
2263
2264
2265
p. will lead to prop2='it “works”' (using ' as string delimiter for clarity).  Or, more extremely
2266
2267
2268
<pre><code class="bash">worker.process.vmOptions=-Dprop1=A “-Dprop2=\””</code></pre>
2269
2270
2271
p. will result in prop2='”'.
2272
2273
2274
2275
h2. Securing z2 for Production Use
2276
2277
2278
h3. Securing Access to Ports
2279
2280
2281
p. By default the z2-base.base distribution is configured to load a number of Web Applications and has, depending on how it is started, accessible debug ports (5000, 5100+x, 5200+x) as well as JMX ports and by default, HTTP access is available on port 8080.
2282
2283
2284
p. However, the Java Virtual Machine may open additional ports and many other applications on the execution environment may do so as well.
2285
2286
2287
p. It is hence important to use a firewall configuration on the execution node, or on the entry gateway to a Virtual LAN setup to make sure that access from any non-controlled infrastructure is only possible to a limited number of ports.
2288
2289
2290
p. We recommend to only make HTTP access (by default port 8080) and SSH (by default port 22) available for remote access.
2291
2292
2293
p. We recommend to use SSH tunneling for all non-application management or debugging access.
2294
2295
2296
p. If you need to provide HTTPS access and want to terminate the SSL connection on the execution environment where you run the application on z2, we recommend to use a Web server like the Apache2 Web Server or NGINX as intermediate reverse proxy for your application. There is excellent documentation and examples available on the internet.
2297
2298
2299
h3. Non-Localhost-Whitelisting
2300
2301
2302
p. Apart from limiting access to ports, you should carefully configure what Web Applications are available for remote access. 
2303
2304
2305
p. While opening port 8080 for remote access would theoretically grant access to all Web applications running on z2 from any client that can reach the execution environment, starting with Version 2.9, the Jetty configuration used with z2-base will prohibit the actual processing of Web request from anywhere but localhost.
2306
2307
2308
p. To enforce that, the configuration of z2-base registers a "handler" with Jetty that filters access from remote clients by a list of regular expressions that must match the requested URL path in order to pass.
2309
2310
2311
p. In order change that, you can either disable the Non-Localhost-Whitelisting by commenting the inclusion of the configuration *z2-nonlocalhostwhitelist.xml** in **environment.base/webServer/z.properties** or **by **update the configuration to include paths for your Web applications.*
2312
2313
2314
p. For example, assuming you have Web applications using the context paths /abc and /def as well as an application on "/" that redirects to one of the others, your configuration might look like this:
2315
2316
2317
2318
<pre><code class="xml"><?xml version="1.0"?>
2319
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
2320
<Configure id="Server" class="org.eclipse.jetty.server.Server">
2321
  <Call name="insertHandler">
2322
  <Arg>
2323
  <New id="NonLocalhostWhitelist" class="com.zfabrik.servletjsp.security.NonLocalhostWhitelist">
2324
  <Set name="patterns">
2325
  <Array type="String">
2326
  <Item>^/abc($|/.*)</Item>
2327
  <Item>^/def($|/.*)</Item>
2328
  <Item>^/$</Item>
2329
  </Array>
2330
  </Set>
2331
  </New>
2332
  </Arg>
2333
  </Call>
2334
</Configure></code></pre>
2335
2336
2337
2338
p. See also "How to secure a Z2 installation":https://redmine.z2-environment.net/projects/z2-environment/wiki/How_to_secure_a_Z2_installation .