Pre-requisites¶

• You need Git installed
• You need a JDK, at least version 7
• You need the ANT build tool

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

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

Change into z2env.core/org.z2env.core.main and run

ant -Doutput=<z2home> -Dsetup=<setup> 

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

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

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

To install/update a web-basic setup (with tomcat and eclipsoid support) that has all addons local (i.e. no further remote synchronization) run:

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

If you want your installation to update itself with the latest addon changes, run

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

Both will be fine for this tutorial.

Check out Understanding the <HOME> to learn more about the generated structure.

Summary¶

• At any time you can update a z2 core installation by running the core build and using the output property to point to your installation
• Using the setup property you can choose between completely local setups (no remote access required - no automatic synchronization from remote either) or mostly remote setups (all except the core will be synchronized from remote repositories).

For now, we will assume you have a z2 core installed in <HOME>. If you built the core as outlined above than <HOME> is the folder z2env next to your core clone.

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. You might need to create that folder.

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

Somewhere between all the log content talking about repositories inspected by z2, you will see a humble "hello!".

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.

Summary¶

• Running a simple program in a modular environment requires no more than declaring the modules and add some code
• Apart from more technical component types, at the heart of the z2 core is to run simple Java main programs

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 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 as described above. Make sure it is in your workspace. If you follow Building the core this means running

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

(Note: Use an absolute path for workspace!)

You can of course simply use the folder you installed into previously as your workspace (not the z2env folder but rather its parent folder!).

Using your IDE, whatever it is, create a new project (in Eclipse choose "Java 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>

Your workspace folder now contains two subfolders z2env and hello.

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

Note: What you just created is a prototypical z2 module structure containing a Java component java (holding implementation) and a Web component web.

• In Eclipse: New / Others / new z2....,
• In IntelliJ: New / Module / z2....

... but beware of the pre-generated configuration. Where it says com.zfabrik change to org.z2env.

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

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.

We call modules with a LOCAL file armed.

Note: By default the dev repo looks for modules beneath the parent folder of the <home> location. Use the system property org.z2env.dev.local.workspace to specify other locations (separated by comma) to check for modules.

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.

Summary¶

• Addons extend z2 with capabilities, such as a Tomcat hosted Web application (albeit running in z2's module environment)
• The dev repository allows to flexibly define local modules. Modules can put into or out visibility by a simple LOCAL marker file.

Pre-Requisite¶

• Have an Eclipse or IntelliJ installation
• Install the Eclipsoid plugin from http://z2-environment.net/eclipsoid/update/site.xml or by searching for "z2" in the IntelliJ Plugin Repository respectively

Steps we are going to take¶

1. Complete the development workspace setup
2. Add a simple Controller

In Eclipse¶

Use the workspace workspace. Create or re-use a Java project hello (if the hello module from above is no Java project yet, open its properties and add the Java Project Facet). You should now have an Eclipse development workspace that has one Java project named "hello". Right-click on the project and choose "Transform into z2 Project". A small "Z" icon should not decorate the project icon.

Add a source folder java/src.impl to the project.

Try "Arm Z2 Projects" and "Disarm Z2 Projects" from the context menu. You should see a LOCAL file showing up and disappearing as well as the "Z" decoration showing a green halo and going back to normal.

Go into Window/Preferences, pick "z2-Environment". Change the port to 8081, set the user to "z*" and the password to "z". Done.

In IntelliJ¶

Add a source folder java/src.impl to the module. Feel free to remove any src source folder Eclipse may have generated for you.

Start a new Project with root folder workspace. Press the "Manage z2-Modules" button in the toolbar. Import the hello module into your IntelliJ project. Open the Settings dialog, pick "z2-Environment". Change the port to 8081, set the user to "z*" and the password to "z". Done.

Independently of whether you use IntelliJ or Eclipse¶

Start z2 as in the previous section but make sure the development support is enabled. Use this command line:

java -Dcatalina.home=/home/me/tomcat -jar z.jar org.z2env.dev.shared/ready hello/web

(possibly you want to turn this into a shell script)

Note: The system state org.z2env.dev.shared/ready will pull up all necessary development support components. Make sure this is part of your to-be-run list.

Regardless whether you are using Eclipse or IntelliJ, press the "Resolve Classpath from Z2" button in the toolbar. This will make sure that all required dependencies for Z2 modules, as far as Java code is concerned, will be resolved for your workspace.

Now add a class SimpleController in java/src.impl and change the following files:

package hello;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

@WebServlet(urlPatterns="/do")
public class SimpleController extends HttpServlet {
    private static final long serialVersionUID = 1L;

    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        String input = req.getParameter("input");
        if (input!=null && input.trim().length()>0) {
            req.setAttribute(
                "output",
                "Hello "+input
            );
            req.setAttribute("input",input);
        }
        req.getRequestDispatcher("/").forward(req,resp);
    }
}

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

java.privateReferences=\
  javax.servlet,\
  javax.servlet.jsp.jstl

<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core_1_1" %>
<html>
<body>
  <c:if test="${not empty output}">
    <p><c:out value="${output}"/></p>
  </c:if>
  <form method="POST" action="<c:url value='/do'/>">
    Input: <input type="text" name="input"><input type="submit" value="go!">
  </form>
</body>
</html>

Make sure the hello module is armed (right-click) by having a LOCAL file.

Now synchronize your running z2 by either:

• Pressing the "Sync with z2-Environment" button in the toolbar
• Pressing ALT+y in your IDE
• Entering "s" on the command line running z2.

Go to http://localhost:8080/hello and check it out.

Summary¶

• Using IDE plugins for Eclipse or IntelliJ you can conveniently develop for Z2.
• Regardless of the component types in use, all class path considerations will be resolved from Z2 and you will never need to change IDE configuration.
• Using the interplay of IDE plugin and the dev repository (see also FAQ) synchronization from the IDE and overlay of modules with local development versions is simple and fast.

Pre-Requisites¶

1. Have all the results from the previous section ready.
2. Start IDE and z2 as above.

Steps we are going to take¶

1. add a new module with a service API
2. reference the module API from the hello module and invoke the service.

In your workspace, use Eclipsoid to create a new z2 Java module goodbye (File/New/Others/z2-Environment/New Java z2-Project).

Until we have the new Eclipsoid plugin ready, open java/z.properties and change all com.zfabrik. prefixes to org.z2env. Essentially the file only needs the line

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

In our API we will only expose an interface and rather leave the implementation hidden in the implementation parts of the module. We do that, as we prefer a strong separation of API and implementation. This is not at all required but a conscious design choice.

package goodbye;

public interface GoodbyeService {

    String sayGoodbye(String in);

}

package goodbye;

public class GoodbyeServiceImpl implements GoodbyeService {

    @Override
    public String sayGoodbye(String in) {
        return "Goodbye "+in+"!";
    }

}

org.z2env.component.type=org.z2env.any
component.className=goodbye.GoodbyeServiceImpl

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

In effect we created the following:

• A module goodbye that has
• A Java component with API and Implementation source code
• An any component goodbye/service that manages the service implementation (as we will see below)

Back in the hello module, we want to use the goodbye service. We apply the following changes:

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

java.privateReferences=\
    javax.servlet,\
    javax.servlet.jsp.jstl,\
    goodbye

package hello;

import goodbye.GoodbyeService;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.z2env.components.IComponentsLookup;

@WebServlet(urlPatterns="/do")
public class SimpleController extends HttpServlet {
    private static final long serialVersionUID = 1L;

    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        GoodbyeService gb = IComponentsLookup.CL.lookup("goodbye/service", GoodbyeService.class);
        String input = req.getParameter("input");
        if (input!=null && input.trim().length()>0) {
            req.setAttribute(
                "output",
                gb.sayGoodbye(input)
            );
            req.setAttribute("input",input);
        }
        req.getRequestDispatcher("/").forward(req,resp);
    }
}

After you have changed the Java references in java/z.properties you might want to press Alt-R or the "Resolve Classpath from Z2" button in the toolbar to have the IDE resolve the dependency for the goodbye module and so that your IDE will not complain about using the GoodbyeService interface.

Now synchronize your running z2 by either:

• Pressing the "Sync with z2-Environment" button in the toolbar
• Pressing ALT+y in your IDE
• Entering "s" on the command line running z2.

Go to http://localhost:8080/hello and check it out.

Discussion¶

What you just implemented is a programmatic component lookup. The first time IComponentsLookup.CL.lookup("goodbye/service", GoodbyeService.class) was invoked, z2 searched for a factory for org.z2env.any components. This specific factory simply created a singleton instance of the Goodbye Service and checked whether the requested interface is implemented. As that held, it returned the actual instance.

In later sections (for now check out How_to_Spring) we will explain how to that extends to the Spring Framework and Dependency Injection in general.

Summary¶

• Being a modular runtime environment, Z2 offers an effective yet simple Java modularization approach
• The module concept of Z2 goes beyond code considerations and includes arbitrary component types such as Web applications

Feel free to apply changes to the Goodbye Service implementation class and have them made effective by synchronizing Z2.

Using remote repositories in combination with the dev repository, z2 offers just that: Integration for all but those pieces you do actually need isolation from changes.

Using z2's synchronization approach rolling out changes to remote installation and scale-outs become a non-issue.

Pre-Requisites¶

1. Have the multi-module setup from the previous section at hand
2. Start IDE and z2 as above.

Steps we are going to take¶

1. check our modules in with some new Git repository
2. add a Git-based component repository component
3. develop with partial overlays

As a first step, create a Git repository. If you have a possibility to do so on some remote location, even better. Otherwise create some local Git repo z2-sample. Say, in a folder git you run

git init z2-sample

Back in your workspace, create a clone of that repository (although it is local, let's pretend it's a remote repository) underneath your workspace folder. I.e. you will have a z2-sample folder under workspace.

Disarm and add the hello and the goodbye modules to the new clone, add and commit the current state. Disarming, i.e. removal of the LOCAL files is important for the sake of this example, so please do.

Push your commits to the origin repository.

Now, as the modules are not armed anymore, z2 will not know about them once we synchronize. By declaring the origin repository as a component repository we will make those modules visible by default.

Go into z2env/roots/remote and add a Git-based component repository by adding a z2-sample.properties file with the following content

org.z2env.systemStates.participation=org.z2env.boot.main/processUp    
org.z2env.component.type=org.z2env.gitcr
gitcr.uri=<uri>
gitcr.branch=master

where <uri> needs to be replaced with the origin repository location. For example, in my case, using a local repository this would be /home/hb/git/z2-sample.

Please restart z2 (new and modified repositories require a restart).

Now you should have the /hello Web application running again. In fact you may delete the modules and the repository clone from your workspace. Let's not do that for a moment though.

Instead, we will do a modification of the goodbye service. To do so, arm the goodbye" module (it should still be present in your workspace), open the *GoodbyeServiceImpl class and change the return value of the sayGoodbye method to e.g. saying "Hasta la vista" rather than "Goodbye".

Synchronize and check what happened with the web app.

Voila!

In real world setups, the repository you clone (Git case) or the projects you check out (Subversion case) are one or few of many. Using the dev repo you can work on an isolated subset of all system components and still be in synch with the overall system. When you are done, using regular source control operations such as commit and push will update the actual system for all involved parties.

Summary¶

• Using regular source control systems such as Git or Subversion you can extend a z2 system
• Using the dev repo you can work on isolated sub systems and still be cleanly integrated
• Being directly hooked up with remote repositories, you do not need to actively update your local installation and updating a remote installation is at most a restart. All you need to worry about is code and structure!
• Being completely defined by repository content, rather than having a development, test, and production codeline in your repositories, you will actually have development, test, and production systems.

Layout¶

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.

Folders and Properties¶

When running z2 from the command line, some logic is applied to derive where stuff is and some defaults apply:

See also Core Layout

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.

A second crucial concept of z2 is that of System Centric Development¶

When working on a software system with many access points and high re-use on a service level, as is typical for business systems, staying quick integration with a team's changes is key. Component repositories can be fed from remotely accessible version control systems such as Subversion and Git. When connecting to a central, team-shared repository, every synchronization will make sure that you are up-to-date with the real source of truth.

Using the dev repo, you can still isolate yourself from changes on part of the system that you are actively working on. After your modifications are completed, rebased, and locally tested, getting a clean and consistent state is just one synchronization away.

The third and final concept is that of a compile-free environment¶

It is within the nature of the synchronization concept, that anything required to happen to have your software available for execution must have happened after synchronization completed. Most preparation steps are executed at first use. This includes the compilation of Java code. Z2 uses the Eclipse Java Compiler for that purpose.

The Component Model¶

See Z2_Modules_intro

Java Components¶

See Z2_Java_components_intro