z2-Environment

p=. Please find the detailed documentation of v2.10 below.

p=. A PDF version can be downloaded here: attachment:"z2_env_fulldoc_2_10.pdf".

p{ text-align:center; font-size:large; }. System Development

p{ text-align:center; font-size:large; }. for Java 

p{ text-align:center; font-size:large; }. with the z2-Environment

p=. Version 2.10

p=. Last updated on:

p=. May 15, 2023

1.  [[#Introduction|Introduction]] 

1.1.  [[#What is the z2-Environment|What is the z2-Environment]] 

1.2.  [[#Online resources|Online resources]] 

2.  [[#Installing and Understanding a Z2 Home|Installing and Understanding a Z2 Home]] 

2.1.  [[#The z2-base Distribution|The z2-base Distribution]] 

2.2.  [[#Home install in 2 minutes|Home install in 2 minutes]] 

2.3.  [[#Folder Structure of a Z2 Home|Folder Structure of a Z2 Home]] 

2.4.  [[#Starting and synchronizing|Starting and synchronizing]] 

2.5.  [[#Important System Properties|Important System Properties]] 

2.6.  [[#The Base Repository|The Base Repository]] 

2.7.  [[#Worker Processes and Home Layouts|Worker Processes and Home Layouts]] 

3.  [[#Anatomy|Anatomy]] 

3.1.  [[#Working on-demand|Working on-demand]] 

3.1.1.  [[#The Resource Management System|The Resource Management System]] 

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]] 

3.2.  [[#Components and Component Repositories|Components and Component Repositories]] 

3.2.1.  [[#Synchronization with updates|Synchronization with updates]] 

3.2.2.  [[#File system support|File system support]] 

3.2.3.  [[#Subversion support|Subversion support]] 

3.2.4.  [[#Git support|Git support]] 

3.2.5.  [[#Maven Repository Support|Maven Repository Support]] 

3.2.6.  [[#Component Types and Component Factories|Component Types and Component Factories]] 

3.2.7.  [[#Dynamic Component Properties|Dynamic Component Properties]] 

3.2.8.  [[#Using Dynamic Property Expressions with JEXL3|Using Dynamic Property Expressions with JEXL3]] 

3.2.9.  [[#Java Naming and Directory Interface (JNDI) support|Java Naming and Directory Interface (JNDI) support]] 

3.2.10.  [[#Link Components and Component Linking|Link Components and Component Linking]] 

3.3.  [[#Unit of Work and transaction management|Unit of Work and transaction management]] 

4.  [[#Constructing a Z2 system|Constructing a Z2 system]] 

4.1.  [[#Add-ons|Add-ons]] 

5.  [[#Developing with the z2-Environment|Developing with the z2-Environment]] 

5.1.  [[#A note on what JDK to use|A note on what JDK to use]] 

5.2.  [[#Workspace development using the Dev Repository |Workspace development using the Dev Repository]] 

5.2.1.  [[#Recommended folder structure |Recommended folder structure]] 

5.3.  [[#The Eclipsoid Plug-in|The Eclipsoid Plug-in]] 

5.4.  [[#Using the Offline Mode|Using the Offline Mode]] 

5.4.1.  [[#How the offline mode is used. |How the offline mode is used.]] 

5.4.2.  [[#Enabling Offline mode at start time |Enabling Offline mode at start time]] 

5.4.3.  [[#Toggling Offline Mode during Development |Toggling Offline Mode during Development]] 

5.5.  [[#In-container unit testing using Z2 Jupiter|In-container unit testing using Z2 Jupiter]] 

5.6.  [[#Retrieving jars from Z2|Retrieving jars from Z2]] 

6.  [[#Managing z2|Managing z2]] 

6.1.  [[#The Basic Admin Interface|The Basic Admin Interface]] 

6.2.  [[#The JMX Read-Only Web Interface|The JMX Read-Only Web Interface]] 

6.3.  [[#The JMX Remoting Command Line Interface|The JMX Remoting Command Line Interface]] 

7.  [[#Enhanced Basis Features|Enhanced Basis Features]] 

7.1.  [[#The Binary Hub Component Repository|The Binary Hub Component Repository]] 

7.2.  [[#The Gateway for Zero-Downtime-Upgrades |The Gateway for Zero-Downtime-Upgrades]] 

8.  [[#Component type reference|Component type reference]] 

8.1.  [[#Core component properties|Core component properties]] 

8.2.  [[#“Any” components (core)|“Any” components (core)]] 

8.3.  [[#Component Factories (core)|Component Factories (core)]] 

8.4.  [[#Data Source components (z2-base)|Data Source components (z2-base)]] 

8.4.1.  [[#Data Source Specific Configuration|Data Source Specific Configuration]] 

8.4.2.  [[#Data Source Types|Data Source Types]] 

8.5.  [[#File system component repositories (core)|File system component repositories (core)]] 

8.6.  [[#GIT component repositories (core)|GIT component repositories (core)]] 

8.7.  [[#Java components (core)|Java components (core)]] 

8.7.1.  [[#Classloaders and References|Classloaders]] 

8.7.2.  [[#Includes|Includes]] 

8.8.  [[#JUL configurations (z2-base)|JUL configurations (z2-base)]] 

8.9.  [[#Link Components|Link Components]] 

8.10.  [[#Log4J configurations (z2-base)|Log4J configurations (z2-base)]] 

8.11.  [[#Main Program Components (core)|Main Program Components (core)]] 

8.12.  [[#Maven component repositories (z2-base)|Maven component repositories (z2-base)]] 

8.13.  [[#Maven component repository fragments (z2-base)|Maven component repository fragments (z2-base)]] 

8.14.  [[#Subversion component repositories (core)|Subversion component repositories (core)]] 

8.15.  [[#System States (core)|System States (core)]] 

8.16.  [[#Web applications (z2-base)|Web applications (z2-base)]] 

8.17.  [[#Web servers (z2-base)|Web servers (z2-base)]] 

8.18.  [[#Worker Processes (z2-base)|Worker Processes (z2-base)]] 

8.18.1.  [[#System Property Propagation from Home to Worker Process|System Property Propagation from Home to Worker Process]] 

8.18.2.  [[#Special considerations when specifying VM options using blanks and quotes|Special considerations when specifying VM options using blanks and quotes]] 

9.  [[#Securing z2 for Production Use|Securing z2 for Production Use]] 

9.1.  [[#Securing Access to Ports|Securing Access to Ports]] 

9.2.  [[#Non-Localhost-Whitelisting|Non-Localhost-Whitelisting]] 

h2. Introduction

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.

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.

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.

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.

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. 

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.

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. 

p. The z2-Environment brings these qualities to the world of Java applications. We call it the _system-centric _approach.

h3. What is the z2-Environment

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.

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.

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.

p. Z2 is strictly implemented on Java:

* Versions before 2.4 require Java 6 and support Java 6 and Java 7  language levels. 

* As of version 2.4, Z2 requires Java 8,

* As of version 2.6, Z2 requires Java 9 and supports Java 9 and Java 10,

* As of version 2.7, Z2 requires Java 9 and supports Java 9, Java 10, and Java 11.

* As of version 2.8, Z2 requires Java 9 and supports Java 9, and higher up to Java 13.

* As of version 2.9, Z2 requires Java 11 and supports Java 15 and higher.

* As of version 2.10, Z2 requires Java 11 and supports Java 18 and higher.

p. See also [[#A note on what JDK to use|A note on what JDK to use]]  for more details.

h3. Online resources

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. 

p. This documentation and high-level information can be found in the Wiki at 

p. "https://redmine.z2-environment.net/projects/z2-environment/wiki":https://redmine.z2-environment.net/projects/z2-environment/wiki 

h2. Installing and Understanding a Z2 Home

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_.

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.

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. 

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.

h3. The z2-base Distribution

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. 

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. 

p. To sum it up:

| Distribution| Contains| When to use |

| 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]] ). |

| 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. |

h3. Home install in 2 minutes

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.

p. For example, from a linux command line prompt you might run:

<pre><code class="bash">mkdir install

cd install

wget http://download.z2-environment.net/z2/z2-base-v2.9.tar.gz

tar xf z2-base-v2.9.tar.gz

z2-base.core/bin/gui.sh</code></pre>

p. installing a z2 Home at z2-base.core in the install folder and starting the development graphical user interface. 

h3. Folder Structure of a Z2 Home

p. Typically a home installation folder has the following file and folder structure:

**bin**

p. This folder holds the actual z2 start code and shell scripts. This is from where you run z2.

**local**

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.

**base**

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.

**config**

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). 

**licenses**

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: 

p. "https://redmine.z2-environment.net/projects/z2-environment/wiki/V29-Licenses":https://redmine.z2-environment.net/projects/z2-environment/wiki/V29-Licenses 

p. Note: To our knowledge, there are no non-business-friendly OSS licenses, but you need to check for yourself.

**LICENSE.txt and THIRD-PARTY-LICENSES.txt**

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.

**work**

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.

**data**

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.

**logs**

p. The place to write log files to. Z2 itself writes its log output into logs/home_0_0.log.

p. A few files are important in the bin folder:

p. *runtime.properties*

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]] .

p. *launch.properties*

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).

p. A typical launch.properties file looks like this:

<pre><code class="bash">#

# alternative VM profiles for the home process

# VM opts

# default

#

home.vmopts=\

	-Xmx64M -cp z.jar \

	-Dcom.sun.management.config.file=management.properties \

	-Djava.util.logging.config.file=logging.properties \

	-Dcom.zfabrik.home.concurrency=5 \

	-Dcom.zfabrik.home.start=environment/home

# override when -mode debug

home.vmopts.debug=-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,suspend=n,server=y,address=5000 -Dworker.debug=true

# override when -mode verbose

home.vmopts.verbose=-verbose:gc -XX:+PrintClassHistogram

</code></pre>

h3. Starting and synchronizing

p. In order to start Z2 in server mode, change into the folder *Z2_HOME/bin*

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).

p. There are several options you may use to alter the default behavior. Most notably, if you start using 

<pre><code class="bash">	./go.sh -mode:debug  </code></pre>

p. the z2 Environment will start with debug settings (see launch.properties above).

p. If you start using

<pre><code class="bash">	./go.sh - -np</code></pre>

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

<pre><code class="bash">	./go.sh -mode:debug - -np</code></pre>

p. you will get both.

p. The general syntax is

<pre><code class="bash">./go.sh <parameters for the launcher> - <parameters for the home process></code></pre>

p. where the launcher is the small program that computes the actual Java command line as indicated in the previous section.

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

p. 	./go.sh -mode:debug - -gui 

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.

p. The gui shell command is a shortcut that spares you the *gui* option. I.e 

p. 	./gui.sh 

*is a short version of *.***/go.sh - -gui***.**

h3. *Important System Properties*

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]] *).

| Property name| Meaning |

| 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. |

| 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. |

| 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. |

| 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.  |

| 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.  |

| 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.  |

| com.zfabrik.java.level| Java language level used for compilation. Can be 6,7,8. Determined by the Java runtime in use. |

| 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. |

| 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. |

| 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]] . |

| 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.  |

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.

h3. The Base Repository

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. 

p. The starting point, from the perspective of the Z2 core is the so-called _Base Repository_.

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. 

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]] .

h3. Worker Processes and Home Layouts

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

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. 

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.

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.

!{height:14.579cm;width:12.002cm;}10000001000003B10000047CA9FE7F60A47D57CC.png!

p. A typical home layout declaration for a single worker process to be executed looks like this:

p. com.zfabrik.component.type=com.zfabrik.systemState

com.zfabrik.component.dependencies=\

  environment/webWorker

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.

h2. Anatomy

h3. Working on-demand

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. 

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.

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. 

p. For example, a change in an API  defined in some Java component may imply that web applications have to be restarted.

p. The abstraction for resources that have dependent resources is the Resource Management system of Z2.

h4. The Resource Management System

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 ). 

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.

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.

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.

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 .

h4. The z2 Command Line, the Embedded Runtime and the Main Runner

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

<pre><code class="bash">java -jar z.jar  -?</code></pre>

p. to see all options.

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.

p. This execution mode can be handy for various purposes:

* 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)

* 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.

p. To facilitate the embedded mode, the Z2 launcher z.jar must be invoked accordingly.

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.

p. When you open a console and run

p. java -cp z.jar com.zfabrik.launch.MainRunner

p. you will get

<pre><code class="bash">z2 MainRunner: Main program execution of z2 components. 

SYNOPSIS 

java -DcomponentName=<component name> -cp z.jar MainRunner <args> 

OPTIONS 

   <component name> 

       A component name in Z2 identifying a main program component 

   <args> 

       Parameters passed to the main program 

NOTES 

Make sure to either set a Z2_HOME environment variable pointing to the  

relevant z2 home installation or specify the system property com.zfabrik.home 

when calling the MainRunner: 

java -DcomponentName=<component name> -Dcom.zfabrik.home=<home folder> -cp z.jar com.zfabrik.launch.MainRunner <args>

</code></pre>

p. explaining the most direct way of using the embedded mode.

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*

p. Running: 

p. java -DcomponentName=com.zfabrik.dev.util/jarRetriever -cp z.jar

com.zfabrik.launch.MainRunner -out test com.zfabrik.dev.util

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.

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.

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.

h3. Components and Component Repositories

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.

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.

p. Component properties are accessible within z2 via the IComponentsManager interface providing IComponentDescriptor instances.

p. Component properties are typically declared via *.properties file resources in stores backing component repositories such as Git, Subversion, or a file system.

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]] .

p. Even more specifically, most existing Component Repositories implement the following folder structures that define components as shown in the right column: 

| …<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. |

| ...<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>) |

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:

* Typically the module matches the development project granularity

* The resolution of Java resources for a component defaults to <module>/java (see [[#Java components (core)|Java components]] ).

* 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.

p. Component repositories define the reality for the z2 environment. So it is important to understand this concept to understand z2.

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.

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. 

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]] .

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:

!{height:6.189cm;width:17cm;}100000010000060D0000023462B7AC2CE1091727.png!

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]] ).

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]] ). 

h4. Synchronization with updates

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.

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. 

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.

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.

p. For example, the home synchronizer (*com.zfabrik.boot.main/homeSynchronizer*) will simply try to attain the home_up state again.

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.

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.

h4. File system support

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*.

p. See [[#File system component repositories (core)|File system component repositories]]  for more details on the configuration of file system component repositories.

_Subversion support_

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. 

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]] .

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 .

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

<pre><code class="bash">com.zfabrik.systemStates.participation=com.zfabrik.boot.main/sysrepo_up</code></pre>

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: 

<pre><code class="bash">http://z2-environment.net/svn/z2-environment/trunk/z2-base.base</code></pre>

h4. Git support

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.

p. Currently all framework development for Z2 happens in Git. All results are however available from Subversion repositories as well.

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.

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 ]] .

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

<pre><code class="bash">com.zfabrik.systemStates.participation=com.zfabrik.boot.main/sysrepo_up</code></pre>

p. to the repository declaration. 

h4. Maven Repository Support

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.

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.

p. Artefacts in Maven repos have a fully qualified name of the form

<pre><code class="bash"><groupId>:<artifactId>:<version></code></pre>

p. or

<pre><code class="bash"><groupId>:<artifactId>:<packaging>:<version></code></pre>

p. By default, a jar artifact *<groupId>:<artifactId>:<version>* will result into a Java component of name

<pre><code class="bash"><groupId>:<artifactId>/java</code></pre>

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). 

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.

p. The z2 core will use lazy component class loaders to make sure that use of include libraries has virtually no runtime penalty.

p. An example configuration of a component repository from a Maven artifact repository may look like this:

<pre><code class="bash">com.zfabrik.systemStates.participation=com.zfabrik.boot.main/sysrepo_up

com.zfabrik.component.type=com.zfabrik.mvncr

mvncr.repository=mavenDefault

mvncr.priority=200

mvncr.roots=\

  org.springframework:spring-context:4.0.2.RELEASE,\

  org.springframework:spring-aspects:4.0.2.RELEASE,\

  org.springframework:spring-tx:4.0.2.RELEASE,\

  org.springframework:spring-orm:4.0.2.RELEASE,\

  org.springframework:spring-web:4.0.2.RELEASE,\

  org.springframework.security:spring-security-core:3.2.2.RELEASE,\

  org.springframework.security:spring-security-web:3.2.2.RELEASE,\

  org.springframework.security:spring-security-config:3.2.2.RELEASE,\

  org.springframework.security:spring-security-aspects:3.2.2.RELEASE,\

  org.hibernate:hibernate-entitymanager:4.3.4.Final,\

  aopalliance:aopalliance:1.0,\

  org.aspectj:aspectjweaver:1.7.4,\

  org.aspectj:aspectjtools:1.6.9,\

mvncr.excluded=\

  org.jboss.spec.javax.transaction:jboss-transaction-api_1.2_spec

mvncr.managed=\

  commons-logging:commons-logging:1.1.2</code></pre>

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>).

p. See [[#Maven component repositories (z2-base)|Maven component repositories]]  in the component reference for more details on configuration properties of Maven component repositories.

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.

p. This is achieved by using Fragments of a  Maven component repository.

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.

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.

p. In order to add a fragment to a Maven Component Repository declare a component of type *com.zfabrik.mvncr.fragment*.

p. See [[#Maven component repository fragments (z2-base)|Maven component repository fragments]]  in the component reference for more details on configuration properties for fragments.

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.

p. Z2's implementation is based on "Eclipse-Aether":https://eclipse.org/aether/ .

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 .

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

p. com.zfabrik.systemStates.participation=com.zfabrik.boot.main/sysrepo_up

p. to the repository declaration. 

h4. Component Types and Component Factories

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.

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. 

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.

h4. Dynamic Component Properties

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.

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.

p. In order to have property values evaluated in a non-static way, the property is extended by a processor type identifier:

<pre><code class="bash"><property name>:<processor type>=<expression></code></pre>

p. with a default processor type “plain”.

p. For example, a propery file, 

<pre><code class="bash">svncr.uri\:plain=http://myserver/svn/myrepo</code></pre>

p. is equivalent to 

<pre><code class="bash">svncr.uri=http://myserver/svn/myrepo</code></pre>

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).

p. However, 

<pre><code class="bash">svncr.uri\:JEXL3=env.SVN_REPO+”/myrepo”</code></pre>

p. will evaluate the environment variable *SVN_REPO* and append a string “/myrepo” (see also [[#Using Dynamic Property Expressions with JEXL3|#jexl3support]] ).

p. Due to a number of reasons, the use of dynamic property evaluation is subject to various constraints:

* 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.

* 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.

* 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.

* 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.

h4. Using Dynamic Property Expressions with JEXL3

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.

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.

p. The following implicit variables are made available by this processor:

| Variable name| Definition| Example |

| system| System.getProperties()| `user dir is ${system["user.dir"]}` |

| env| System.getenv()| "JAVA_HOME is ${env.JAVA_HOME}" |

| 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”] |

| components| IComponentsManager.INSTANCE| components.getComponent("mymodule/mycomponent").getProperty("myProp") |

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

<pre><code class="bash">hostName\:JEXl3=env.hostName

database\:ext=_THE_DB_

ds.prop.url\:JEXl3=`jdbc:derby://${this.hostName}/${this.database}`</code></pre>

p. would be evaluated resolving across processors and with correct substitution in the JEXL expression.

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

<pre><code class="bash"> `Hallo this is ${system["user.name"]}`</code></pre>

p. does indeed evaluate to a string. As does

<pre><code class="bash"> "Hallo this is ${system[\"user.name\"]}"</code></pre>

p. (without processing the ${} expression) and more advanced

<pre><code class="bash">system["os.name"].startsWith("Linux")? "We are running on a Linux OS" : "We are running on something else"</code></pre>

p. but not

<pre><code class="bash">500+10</code></pre>

p.  which is indeed an integer.

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.

h4. Java Naming and Directory Interface (JNDI) support

p. Components in the z2-Environment may be looked up via JNDI. The functionality is essentially equivalent to lookups via the *IComponentsLookup* interface.

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

<pre><code class="java">IComponentsLookup.INSTANCE.lookup("mymodule/dataSource",javax.sql.DataSource.class); </code></pre>

p. is equivalent to 

<pre><code class="bash">new InitialContext().lookup("components:mymodule/dataSource?type=javax.sql.DataSource");</code></pre>

p. and both calls return a (shared) data source instance.

h4. Link Components and Component Linking

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.

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.

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.

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:

<pre><code class="bash">#

# link to environment.base for defaulting

#

com.zfabrik.component.type=com.zfabrik.link

link.targetComponent=environment.base/webServer</code></pre>

p. Link components are built-in with z2’s component handling and operations are delegated to declared target components:

* Lookup as implementation of an interface or class via e.g. IResourceHandle.as(…) or IComponentsLookup.lookup(…) in general (see the exception below).

* Component resource access via e.g. IComponentsManager.retrieve(…).

p. Some operations are not delegated however:

* Lookup as IResourceHandle or IResourceObserver

* Component Descriptor retrieval via IComponentsManager.get()

* Search of components via IComponentsManager.findComponents(…).

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.

p. A target component may itself be a link component. Where link resolution is implemented, it is done indefinitely until reaching an ordinary component. 

h3. Unit of Work and transaction management

p. The z2-Environment does not mandate any specific way of implementing transaction management. 

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.

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. 

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.

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.

p. It can be looked up using the global JNDI name 

<pre><code class="bash">components:com.zfabrik.jta/userTransaction</code></pre>

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.

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.

p. In terms of the JTA implementation, this behaves as if there is already a transaction open on the thread. 

p. The WorkUnit API supports nesting and suspending of units of work. With the JTA implementation this corresponds to nested and isolated transactions.

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.

h2. Constructing a Z2 system

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.

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. 

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. 

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.

p. Before moving forward on that, let's have a look at the add-ons. 

h3. Add-ons

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]] ).

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. 

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.

h2. Developing with the z2-Environment

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.

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.

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.

p. The whole approach to local development using the z2-Environment is currently based on two tools:

* The Development Repository – a component repository implementation that allows you to selectively and quickly test modifications

* The Eclipsoid Eclipse plug-in. A plug-in to the popular Eclipse development environment that resolves project dependencies from a running z2-Environment.

h3. A note on what JDK to use

p. Different Z2 versions support or require different Java versions. 

| Z2 Version| Supported Java Versions| Highest Supported Language Level |

| < 2.4| 1.6, 1.7| 1.6 |

| 2.4, 2.5| 1.8| 1.8 |

| 2.6| 9-10| 9 |

| 2.7| 9-11| 11 |

| 2.8| 9-13| 13 |

| 2.9| 11-16| 15 |

| 2.10| 11-18| 18 |

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.

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.

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

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.

h3. Workspace development using the Dev Repository 

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. 

p. It expects to find a component repository structure as detailed in  [[#Components and Component Repositories|Components and Component Repositories]] . 

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.

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:

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.

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.

p. That sounded a little complex, but as you will see next, together with the Eclipsoid tool it all rounds up nicely.

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. 

p. By modifying the system property *com.zfabrik.dev.local.workspace* you can influence where the Dev Repo scans for armed modules.

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 

p. folder1/folder2/folder3/LOCAL

p. would be found, which would then make up for module *folder3*.

*Recommended folder structure *

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.

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.:

<pre><code class="bash">workspace/z2-base.core

workspace/com.acme.some.project

...</code></pre>

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:

p. install/z2-base.core

install/some.other.repo.clone

install/workspace

...

p. Note: In both cases, the search path for “armed” project is the same for the Development Repository  (see above).

h3. The Eclipsoid Plug-in

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 

*http://localhost:8080/eclipsoid/update/site.xml*

p. Alternatively, you can install it from the z2 environment server at

*http://www.z2-environment.net/eclipsoid/update/site.xml*

p. This plug-in provides a number of useful utilities for working with Z2. The most important functions are:

# Trigger synchronization of the running z2-Environment from the IDE (Sync)

# Download of dependencies as .jar files from a running z2-Environment (Resolve)

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. 

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.

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.

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.

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.

!{height:10.795cm;width:15.201cm;}10000001000004AD00000352168C98698EC3FAA4.png!

p. _Sync_ and _Resolve_ can be invoked by pressing Alt+Y or Alt+R respectively or by clicking on the Z2 toolbar buttons. 

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. 

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.

h3. Using the Offline Mode

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.

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.

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.

h4. How the offline mode is used. 

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". 

p. This works regardlessly of how this system property is set in the home process. Worker processes receive an updated value upon synchronization. 

h4. Enabling Offline mode at start time 

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.

h4. Toggling Offline Mode during Development 

p. Alternatively the offline mode may be switched on or off using a check box on the Z2 GUI.

h3. In-container unit testing using Z2 Jupiter

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/ .

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.

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.

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.

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.

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.

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 Wiki page on z2Unit to learn how to practically use Z2 Jupiter.

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/ script for example. A typical application is to run Z2 Jupiter integration tests as part of your test automation effort.

p. See in particular the following section on how to download dependency libraries from Z2 for use with ANT.

h3. Retrieving jars from Z2

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.

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.

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.

p. One particular use case is to retrieve Jars from Z2 within an ANT script, for example to automate unit testing.