First steps with Z2¶

« Step 2 - Install and run in 5 minutes

Prerequisites¶

You need a z2-base installation as described on the previous page.
Furthermore you need the Eclipse-IDE (one of Galileo, Helios, Indigo, Juno or Kepler is fine) and the Egit plug-in:.

First steps with the z2-Environment¶

Next, we will look at development for Z2 with Git using Eclipse. Please stop the server before you continue.

In order to have module modifications from locally cloned repositories discovered by Z2, it is required for the repositories and workspace to be siblings to each other. Go back to the "z2-base" directory (cd ../.., if you are inside the "bin" directory) and create a folder called "workspace" - this will be used as the workspace root for Eclipse:

:bin$ cd ../..
:z2-base$ mkdir workspace
:z2-base$ ls -l
total 0
0 drwxr-xr-x   2 mr_x  staff   68  7 Sep 16:34 workspace
0 drwxr-xr-x  12 mr_x  staff  408  7 Sep 15:11 z2-base.core
:z2-base$

Now start Eclipse and choose z2-base/workspace as your workspace folder.

For convenience, we recommend to create an "External Tool Configurations" to start the Z2 Graphical User Interface (GUI) from within your development environment. Add the start script gui.sh (or gui.bat on Windows) from the z2-base.core/bin folder as the "Main Location".

When running you should see a new window labeled "Z2 Home (z2-base)":

The z2-Environment provides an Eclipse plug-in called "Eclipsoid" that has a lot of neat utilities and one really important feature: Dependency resolution from a running z2-Environment.

Here's the catch: When developing with Eclipse, projects in your workspace may require Java types from other projects to compile. Eclipse will try to verify that, every time you save a source code modification. When working on a non-trivial system, you may have a lot of dependencies that you will typically not want to see clutter your workspace. That is where the plugin comes into the game. This way you can checkout and focus on a project subsets while the Eclipsoid plug-in provides the transitive closure of all required prjects and libraries.

Other features provided by the Eclipsoid plug-in that are explained in more details on the Eclipsoid wiki pages.

Installation of the Eclipsoid plug-in¶

You can install the Eclipsoid plugin directly from the Eclipse Marketplace by searching "eclipsoid" or simply from here:

https://marketplace.eclipse.org/content/eclipsoid-z2-environment-eclipse-plugins

After installation you should now see a new menu entry labled "z2-Environment" and two new icons:

NOTE (important): When you use the plugin and you get authentication errors, please check for the user/password used at Window/Preferences/z2-Environment. By default use user z* (yes, "z" followed by an asterisk) with password z.

Changing source code and check the result¶

To change source code, we need a project in Eclipse. Let's change the simple calculator Web application that is contained in the base repository.

To do so, we need to

1. make the Git repository available in Eclipse's Git tool EGit,
2. import the project into Eclipse and
3. change the project and check the result.

The first two steps can be done the regular Eclipse way or using the Eclipsoid plugin - both leading to the same result. Let's try latter:

In the new "z2-environment" menu choose the entry labled "z2-Repositories view".

This will open a view like this:

This view lists all repositories currently known by the running system.

(Note: The Eclipsoid plug-in connects by default to the Eclipsoid Web application on http://localhost:8080/eclipsoid/ that provides all kinds of runtime information to the plugin. The connection data can be customized on the "z2-environment" preference page).

The repositories in the view is called com.zfabrik.boot.config/baseRepository containing the Z2 foundation services. It also contains a sample web application that we are going to open and change.

Right-click on the base repository and choose "Clone Git repository" from the context menu. This will create a clone from http://git.z2-environment.net/z2-base.base next to the z2-base.core repository inside your z2-base directory.

To import the project want to work on into your workspace, either import the "com.zfabrik.samples.calculator" from the z2-base.base repository in the Git perspective or return the the z2-Repositories View and expand the "com.zfabrik.boot.config/baseRepository" node and further its "z2-projects" child node. You will see all projects that are stored inside this repository.

Right-click the "com.zfabrik.samples.calculator" project and choose "Import Project" from the context menu. This does the same as the import project action of the Git repositories perspective

Once the project is imported go to the Java Package Explorer view and drill down to /com.zfabrik.samples.calculator/java/src.impl/com/zfabrik/samples/calculator/impl/Calculator.java, open the the class via double click. The result should look like this:

In the source is annotated with colored squiggles and red x-markers indicating that Eclipse's compiler is not able to resolve certain identifiers. If you want you can check the classpath of the project and indeed there are only three entries: One for the JRE, one for the sources, and one called "Eclipsoid: z2-Environment Build Container". This container will resolve the incomplete class-path when it is asked to do so. Click the toolbar icon or hit <Alt+R> to trigger a refresh of that build container. All red x-markers should be gone by now.

Before we change the code let's have a look at the current state. Launch http://localhost:8080/calc and play around with the calculator. You might miss some operations like logarithm or square root which we are going to add now. Go back to Eclipse and the Calculator class. Uncomment one line inside the enum OP definition:

private enum OP {
    CE, C, open, close, 
    sqrt, pow, ln, epowx,
    sgn, dot, eq, pi, 
    add, sub, mult, div, 
    sqr, inv, illegal
};

Scroll down to method doOp() and uncomment the section from case sqrt: to case epowx: (line 154 to 170):

...
    break;

case sqrt:
    new Sqrt().addTo(this.stack);
    break;

case pow:
    new Pow().addTo(this.stack);
    break;

case ln:
    new Ln().addTo(this.stack);
    break;

case epowx:
    new EPowX().addTo(this.stack);
    break;

default:
...

The implementation classes of these operations do are already exists.
We must also add the operations to the visual layout which is implemented as a JSP file. Navigate to /com.zfabrik.samples.calculator/web/WebContent/calc.jsp and open the file. Scroll down to line 102 and uncomment the block annotated with "uncomment me":

...
<button type="submit" name="op=CE" title="C">CE</button>

<button type="submit" name="op=sqrt" title="r">&radic;</button>
<button type="submit" name="op=pow" title="^">x<sup>y</sup></button>
<button type="submit" name="op=ln" title="l">ln</button>
<button type="submit" name="op=epowx" title="e">e<sup>x</sup></button>

<button type="submit" name="op=pi" title="p">&pi;</button>
...

Now what happens next is really important to understanding the principles behind Z2. In order to test our modification we will not deploy any kind of archive. Instead we will make sure it considers the project in our workspace a preferred version of the calculator project.

From the Z2 point of view the Eclipse workspace is yet another component repository. We call the implementation the Dev-Repository, because it is obviously suitable for local development.

To make the inclusion of a specific project into the Dev-Repository effective, we will arm it. This is so you can choose whether a local workspace version of a module should be considered or rather not. Practically, arming means nothing else but putting a file called LOCAL into the project folder.

When we ask the Z2 server to check for new changes (we say "to synchronize the server"), it will find two versions of our calculator project: one inside the z2-base.base repository and one inside the Dev-repository (i.e. your workspace). Because of the preference rule above, the version in your workspace will be considered with preference.

To "arm" the calculator project right-click the project "com.zfabrik.samples.calculator" in the Java Package Explorer and choose "Arm z2-Projects" (which, a indicated, does in fact nothing but putting an empty LOCAL file).

You will see a green "z" decoration at the upper left edge of the Java icon in the package explorer: .

After we specified that the workspace version of the calculator project should win over the one in the Git repository we can trigger the z2 synchronization: Choose "Sync with z2-environment" from the "z2-environment" menu, click the new z-icon or hit <Alt+Y>.

The connection with the Z2 server is established via he Eclipsoid plug-in over http. In situations where the Web server cannot be started, the Eclipsoid web application will not be available. In this case the z2-gui is the only way to trigger a synchronization (except of a shutdown and restart). You will also see that the log-messages in the z2-gui log pane has changed and that the server has invalidated and restarted one resource:

09/28 13:14:47 [36]...entRepositoryImpl [800]: Pulled deltas within 874msec from GitCR com.zfabrik.boot.config/baseRepository (origin=http://git.z2-environment.net/z2-base.base, branch=v2.1, OPTIONAL, root=/Users/udoo/dev/temp/z2-base/z2-base.core/run/bin/../../work/repos/95f655a0/git)
09/28 13:14:47 [36]...hronizationRunner [800]: Found 2 invalidation candidate resources
09/28 13:14:47 [36]...hronizationRunner [800]: Invalidated 0 resources
09/28 13:14:47 [33]...ent/webWorker@0.2 [800]: 09/28 13:14:47 [19]...stemStateResource [800]: Left system state: environment/webWorkerUp
09/28 13:14:47 [33]...ent/webWorker@0.2 [800]: 09/28 13:14:47 [19]...pp.WebAppResource [800]: Stopping Web App (/calc): com.zfabrik.samples.calculator/web
09/28 13:14:47 [33]...ent/webWorker@0.2 [800]: 09/28 13:14:47 [19]...worker.WorkerSoul [800]: Invalidated 2 resources
09/28 13:14:47 [33]...ent/webWorker@0.2 [800]: 09/28 13:14:47 [19]...pp.WebAppResource [800]: Starting WebApp: com.zfabrik.samples.calculator/web
09/28 13:14:48 [33]...ent/webWorker@0.2 [800]: 09/28 13:14:48 [19]...pp.WebAppResource [800]: Done starting Web App (/calc): com.zfabrik.samples.calculator/web
09/28 13:14:48 [33]...ent/webWorker@0.2 [800]: 09/28 13:14:48 [19]...stemStateResource [800]: System state attained: environment/webWorkerUp
09/28 13:14:48 [36]...mponentRepository [800]: Overriding module com.zfabrik.samples.calculator: com.zfabrik.dev.repo/devRepo

Now it's time to check the result: http://localhost:8080/calc - voilà!

You should repeat these steps a few times: Change the source code (e.g. adding more new calculator operations like sine, cosine, tangent...), hit <Alt+Y> and check the result, so you will get a feeling of how fast development round trips can be!

What's next?¶

If you prefer using subversion, there is absolutely no restriction. On the contrary, the whole approach may even look more natural with Subversion compared to Git as a lot of unnecessary downloading can be omitted. Please have a look at

• Step 3 - First steps with Z2 on SVN
• Repositories

Please visit the Samples. In most cases, trying them is straight-forward and instructive.

Want to understand it better? There are some more detailed articles in this wiki. However, for a structured reference and introduction, you are strongly encouraged to start reading the documentation in parallel to any other investigation either via the samples or the howtos:

• Start reading the v2.5 documentation
• Check out some of the blogs at Blogs

Thanks!

---