Developing in the z2-Environment

Please make sure you read the previous sections, starting at Installation.

In this section we will see how to develop for the z2-Environment. Keep in mind that there is not much of a difference whether a single person or a team does so.

Why is this important?

While that may seem counter-intuitive, ease of development for a single developer is often bought by a late but significant investment into learning build automation, version control and so on. The z2-Environment provides a convenient development approach without compromising its team development capabilities.

We will make use of the Eclipse development environment. If you did not install it as described in section Installation, please do so now.

Subversion users:

Please make sure you have the Subversion client plugin Subclipse installed (unless you feel certain using your other favorite Subversion client).

GIT users:

Please make sure you have the GIT client plugin EGIT installed.

Note: You do neither need Eclipse nor Subclipse nor eGIT to develop and run programs for the z2-Environment. In contrast to many other environments you do not even need any build automation or other tools (not even a compiler) to write code and test it. A simple text editor is sufficient. Nevertheless, on the comfort side, a true IDE and the Eclipsoid plugin, will make a significant difference and we will see how to modify an isolated part of a well-defined software system (albeit a small one in the base installation) at maximum development comfort and with minimum upfront effort.

Checking Out

At first we will modify the Apache Wicket based image library application. Opening the workspace_z2_base (subversion) or the workspace (GIT) workspace folder in Eclipse should get you here (or similar):

Let's check out some project:

Subversion users:

Please open the "SVN Repository Exploring" perspective. On the repository view expand the samples folder in the repository location http:/www.z2-environment.net/svn/z2_base/branches/v2.0 that we set up in the previous section. Right click on the project samples.wicket.imagelib and check it out as a project into your workspace.

GIT users:

Please open the "GIT Repository Exploring" perspective. On the repository view expand the samples repository and import the project samples.wicket.imagelib into your workspace.

The image library application lists pictures that have been uploaded before. In particular it display a picture title in a somewhat decorated form:

It uses a utility class from another project for that.

We want to change that and rather than decorate the picture title, randomize the title string.

The class we need to change is called stuff.wickil.pages.LibraryDataView. Please open the class in Eclipse. You should see something like this:

But wait! That doesn't look good, does it?

What's the Problem?

Now we do actually have two problems:

  1. How will we make our modifications seen by the runtime, so we can test them?
  2. How will we make use of Eclipse's built-in background code analysis and compilation that offers us compile checking, code completion, and much more?

If you would be allowed to commit changes back into our repository, you could fix the first problem by simply doing that and pressing "Sync" on the graphical  console to force a synchronization of the runtime. In reality however you would not want to commit every single change to a central versioning system for testing.

In order to simplify testing from a workspace, the base installation provides a second repository implementation, that overlays the default repository implementation that reads from the central repository.

It pulls all its content from the project folders in your Eclipse workspace (and all locale repository workspaces in the GIT case). It will consider all project folders that contain a file called LOCAL (whose content will be ignored). Effectively your z2-Environment will live on two repositories: One central - keeping you in sync with the team and one local workspace based repository that allows you to selectively isolate pieces of the system and modify them:

So, in order to test your modifications you can simply drop an empty file LOCAL into samples.wicket.imagelib and press "Sync" on the GUI every time you want to test a modification. Once you are done, you simply commit changes and remove the LOCAL file again.

But hold on, there is more:

In order to address the second issue (i.e. how to make Eclipse compile your workspace), you would normally either check out all projects and libraries that already existing projects in your workspace require to compile or you would use some other tool (e.g. maven) to build and/or retrieve anything needed from somewhere. There is a simpler way.

The z2-Environment provides an Eclipse plugin, called Eclipsoid, that makes use of  the fact that your local runtime can provide all binaries needed without any external build tool, so that Eclipsoid can fill a classpath container, i.e. a custom class path of a project in an Eclipse workspace accordingly.

Installing Eclipsoid

Make sure the runtime is up. In Eclipse open "Help" / "Install New Software... " and enter the update site

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

Eclipse should offer the Eclipsoid Feature for installation. Please just do that (after you reviewed and accepted the license).

After restarting Eclipse you will find two new "Z" buttons on the top toolbar, a preference page called "Eclipsoid" in your preferences, and that the sample.wicket.imagelib project will be decorated with a black "Z". That is because it has the Eclipsoid Library added to its build path (as you will find out when opening the project's preferences).

Press the right "Z" button ("Sync with Z-Server") or press Alt+R on your keyboard. This will do two things: It will trigger a synchronization of the local z2 runtime and it will fill the Eclipsoid class path container of all projects in your workspace accordingly to their dependency declarations (In case you get an error, please make sure that the right port settings "8080" are configured in Window/Preferences/Eclipsoid). When that has completed, everything should compile and when you open the class path container in the sample.wicket.imagelib project you will see an impressive number of libraries downloaded to match the dependencies of the project as declared with the z2-Environment (have a look at the z.properties in "java" - we will not go into details here though):

Why is this important?

Sofware systems easily grow beyond single projects - or even beyond what developers can conveniently manage in one workspace. In fact: In most cases you do not care about what is needed to make a project compile, you simply want to work on one or a few specific projects to implement a feature or correct a bug. Traditionally, it is the environment that makes you fix and update a local setup that eventually let's you do what you wanted to do in the first place: Work on some specific piece of a much larger system. While that may be acceptable when developing within the same set of projects for a long time, it is unacceptably tedious and error-prone when considering support situations and when switching releases and code lines is a frequent necessity.

Now that we are finally set.... let's really do start modifying some stuff. Please continue with Develop Part 2.