Intro¶

This project is for the development of z2-environment version 3.0.

Version 3.0 is a major refactoring release of z2 with new repository code lines and complete package renaming.

Essential Differences between v2.3 and v3.¶

• All the typical declarations and package names are no longer com.zfabrik.<something> but rather org.z2env.<something>
• The <z2 home> layout is completely new and more flexible
• The essential component types that can be invoked from the core is system state and main program.
• While Jetty is still contained to support Eclipsoid and z2Unit, we support a pre-installed Tomcat as application container.
• The core is lighter and more dedicated.
• There will be substantially less built-in application support like
  • a local JTA implementation
  • No worker suppport without a corresponding add-on.

• Make the lower parts of z2 more accessible and easier to understand: While z2 previously started System Centric, we now close the gap from the ordinary main program.
• Increase the OSS flavor of z2

Draft Intro Documentation¶

Getting Started¶

To understand how z2 works, you need to understand at most what are z2 modules and components and what are component repositories and how these concepts interplay.

Check out understanding-z2 for that.

It is simplest to start by running a simple Java main program in z2 or a simple Web App.

Follow this trail:

• Building the core
• Running a Hello World main program
• Running a Hello World Web App

Building z2env-core¶

First clone http://git.z2-environment.net/z2env.core

git clone http://git.z2-environment.net/z2env.core

Switch into org.z2env.core.main and run

ant -Doutput=<location of z2 home> -Dsetup=<preconfigured roots> 

where <location of z2 home> is where you want to install z2 (the <z2-home>) and <preconfigured roots> is a choice of pre-configured content, actually component repositories.

If you omit output it will default to gen/dist. If you omit setup, no content will be pre-configured will be modified.

Check the folder setups for available setups of the core build. These can be local (all repos will be cloned locally) or remote (repos will be remoted).

In general this build always updates only boot, z.jar, roots. It will not remove anything.

Example to install/update a core only into ../../z2env:

ant -Doutput=here 

To install/update a web-basic setup (with tomcat and eclipsoid support) with updates from remote repos:

ant -Doutput=../../z2env -Dsetup=web-basic-remote

Running a Hello World main program¶

For now, we will assume you have a z2 core installed in <HOME>. In its purest form, all the core can actually execute is simple Java main programs.

Being in a modular environment, even if we only want to say „Hello World“, we need a module. Let's call it the greeter module. In order to have a main program run by z2, we need to also declare a component for it, as that is what we tell z2 to run (not a class – mind you – but rather a component in a module). Assuming we use the local component name hello, than the absolut component name is

greeter/hello

Finally, as this component actually has implementation code, we need to declare a Java component. By convention this is

greeter/java

Now, after installing in <HOME> the place to simply drop a module is under <HOME>/modules. All in all, here is the complete structure to create:

org.z2env.component.type=org.z2env.main
component.className=greetings.Main

org.z2env.component.type=org.z2env.java

package greetings;

public class Main {
  public static void main(String[] args) {
    System.out.println("Hello!");
  }
}

That gives us the two components of module greeter. To run this on the command line, run

java -DcomponentName=greeter/hello -jar z.jar

Now, obviously this sample is not worth a modular execution environment. But even from here, you could check your module in with some Git repository that is referenced from the roots and all other users of the same repo would be able to run your component without installing anything.

Running a Hello World Web App¶

This introduction explains how to connect a z2 core to a given Tomcat installation and how to develop a simple Web Application.

Furthermore it describes how to use the Dev Repository and the Eclipsoid plugin for the Eclipse or the IntelliJ development environment.

Pre-Requisites¶

• We assume the Eclipse IDE.
• Please install the Eclipsoid Plugin from http://z2-environment.net/eclipsoid/update/site.xml
• We assume a development workspace in workspace.
• Have a local Tomcat (7 or higher) installation.*

Steps we are going to take¶

1. Create a module with a simple Web app
2. Make it visible to Z2
3. Run the Web App in a Tomcat Web Container

At first get yourself a z2env core with the web-basic-local or web-basic-remote setup. Make sure it is in your workspace. If you follow Building the core this means running

ant -Doutput=workspace/z2env -Dsetup=web-basic-remote

Using your IDE create a new project hello in workspace with the following structure:

org.z2env.component.type=org.z2env.java
java.privateReferences=\
    javax.servlet

org.z2env.component.type=org.z2env.tomcat.webapp
webapp.path=/hello

<html><body>Hello! Did you know that 7*7=<%=7*7%>?</body></html>

So far, that's it. We will touch on the LOCAL file later.

When we run Z2 knowing this Web Application, it will attempt to start a Tomcat Web Container that will serve the application's content. To do that, it needs to find one.

In order to tell Z2 where to look, you can either set an environment variable CATALINA_HOME (you might have already – it's the Tomcat standard) or specify an environment variable catalina.home.

To be on the safe side and assuming the location is /home/me/tomcat, we open a terminal, change into workspace/z2env and run

java -Dcatalina.home=/home/me/tomcat -jar z.jar hello/web

Note, unlike for the main program, the command line will not return. Instead you can enter „q“ to quit or „s“ to synchronize. But first let's open a browser and check out

http://localhost:8080/hello

Now on to that LOCAL file. Unlike for the Hello World main program, this time it was to so-called Dev Repo that made our module available to z2.

The dev repo is a key component to the development approach with z2. It checks for all modules that have a LOCAL file and that are stored some levels deep, relative to the parent folder of the z2 home (by default), which not so coincidentally is our workspace.

Try this:

1. Remove LOCAL
2. Enter „s“ for synchronization.
3. Check the URL above (should say „not found“)
4. Create a LOCAL file again
5. Synchronize
6. Check again.

Similarly, from now on, changes made to the hello module will be picked up, whenever you synchronize.

Developing with Eclipsoid¶

Add some real code for the web app, resolve classpath in IDE with Eclipsoid

TBD

Multi-Module Development¶

TBD

Going System-Centric¶

TBD

Getting more real by adding a remote repo as system repo.

Develop by checking out modules and using the Dev Repo.

Understanding the <HOME>¶

We call an installation of a z2env core a <home>. The file structure of the <home> consists of few but important locations:

We use the modules repository for example for command line experiments and simple hacks. It is not as useful for regular development operations as is the dev repo.

Understanding Z2¶

Most of the concepts that make up z2 can be derived from the desire to efficiently develop standard Java Web Applications that are defined in a central system definition. Add to that the wish to avoid all that build complexity and the desire for a practically usable modularization approach.

Once you loose the ability to tweak some build script or configuration to describe how to package a Web app or some libraries, you need some structural hint and simple declarations providing sufficient information.

Secondy, assuming you want to apply changes at runtime, you need some way of determining what to unload at runtime, given some changed file. Again: Structural information needs to present that maps to runtime state.

Finally, as we want some support for modular application development anyway, why not make modules our essential structure. As we have not only code but also Web Applications, Data Sources, Background Jobs and much more to consider, we add components with type into the mix. Voila.

Component Repositories provides modules and components to z2. A component is prefixed by the module name:

<global component name> = <module name>/<local component name>

In fact, the typical component repository has a file system style structure that is made up exactly like that.

Structure from repo root:

Note that some components, like Web applications and typically Java components have file resources, such as HTML files or Java source code files, while other components, such as main program declarations or data source declarations, so not.

There are some conventions around this naming scheme. In particular, by convention, whenever a component requires Java implementation, z2 will first look for a component named java of the same module. As for example in the Hello World example.

To give you an idea what this model translates to at runtime consider this: At runtime, the static component is turned into a Resource instance by a component type implementation (that, in fact, is provided by another, built-in component type).

Dependencies, for example those between Java components, translate into dependencies between resources that are observed during invalidation of resources. This introduces invalidation and synchronization.

A crucial concept of z2 is that of a synchronization.

For fast development roundtrips and in some cases for general configuration updates, it is desirable to not require a complete restart of a Java Virtual Machine process but rather just to change runtime state accordingly.

In z2 a synchronization describes the following process:

1. Check for changes in component repositories
2. Based on changes found, identify components affected and invalidate associated runtime resources incl. dependent resources.
3. Try to attain target states

That is, whenever you do a change and trigger a synchronization from your IDE, this is exactly what happens: Identify what needs to be thrown away, make sure to remove dependent stuff as well, bring up what needs to be running.

The Component Model¶

See Z2_Modules_intro

Java Components¶

See Z2_Java_components_intro