How to run a sample¶

-- OUTDATED ---

Various z2-based sample system configurations have been prepared as Git repositories.

Assuming you know the repository URL these three steps (with or without Eclipse) are all there is to do.

While these instructions are for Git users, they can be applied to the Subversion case quite similarly as described below.

Note: If you experience problems reaching out to the internet, you may need to configure some proxy settings. Please see How_to_proxy_settings for how that is done.

Eclipse users¶

Most likely you will want to look at code or configuration files of a sample. That is why we recommend to start from within the Eclipse IDE. If you prefer the command line or another IDE, please proceed to From the command line.

Open Eclipse with a new workspace in a new folder, say sample. Note: We will clone repositories as siblings to your workspace. So let's assume your workspace is sample/workspace.

1. Prepare a z2-base installation¶

As the location where repositories are cloned to matters, it is simplest you open the Git tab in the Eclipse preferences and enter "${workspace_loc}/.." as default repository location.

Open the Git Perspective and clone the z2-base.core repository from this URL http://git.z2-environment.net/z2-base.core. For convenience choose to import all projects into the workspace or do so after cloning has completed. You should end up having a project core in your workspace. That project is the z2 core that will fetch dependency resources as needed later on.

2. Clone the sample repository¶

Now repeat the same with the repository for the specific sample. It is important that the repository is cloned as a sibling to the core, So that the core can pick up modules defined in the sample.

3. Start and introspect¶

You can launch Z2 from Eclipse by the launcher file in the root of the core project (or by navigating to Run / External Tools / External Tools Configurations... and pick the launcher). A GUI wrapping the console should open up and you are ready to go.

Once it is running, import the projects from the sample repository into your workspace, so that you can have a look at them. If you have previously installed the Eclipsoid plugin (see Step_3_-_First_steps_with_Z2_on_Git) you can conveniently resolve all compilation dependencies with one click from within Eclipse.

Using IntelliJ¶

IntelliJ z2 plugin shows how to install the z2 plugin and its basic features.
You can checkout the z2 repositories using VCS -> Checkout from Version Control... but make sure that you don't create a new project when IntelliJ asks you if "would you like to create a new IDEA project for ..."!

Furthermore make sure that the repository folders are located directly beneath the project folder:

.../my-project
     /.idea
     /z2-base-core
     /z2-samples.xyz

Once z2-base.core is checked out navigate to Preferences -> Project Settings -> z2-Environment and click "Search z2-Home" which should find the z2-base-core folder inside your project; press ok.
Still in the preference pane select Project Settings -> File Colors and add a new label to the local colors. As scope select "Armed z2-Modules" and choose a color you like and press ok and close the
Settings pane with ok. Now armed z2-modules will be displayed with the selected color.

Now launch the z2-environment from Tools -> Launch z2-environment...

Once it is running, import the projects from the sample repository into your workspace, by selecting the menu "Manage z2-modules" inside the toolbar. This opens a popup window showing
the checked out repositories as root folders and their modules as children. Choose the modules belonging to the samples repository or simply select the sample repository node and press ok.
This will create modules for each selected z2-modules inside your project. Since z2-modules in the samples repository are armed by default the modules should be displayed with the color selected above.

Of course the java classes will contain a lot of errors coming from unresolved dependencies. Choose "Resolve z2-classpath" in the toolbar which will download all missing jars and add them
to the modules.

From the command line¶

All you need is Java Runtime Environment (JRE) of at least version 6. Other pre-requisites, for example some database setup may be required based on the specific example, i.e. stuff that cannot be covered here.

1. Prepare a z2-base installation¶

Create a folder to hold the installation. We will assume that folder is called sample

In sample execute

git clone -b master http://git.z2-environment.net/z2-base.core

Go into sample/z2-base.core/run/bin and run

./gui.sh

or

gui.bat

depending on your operating system. A simple graphical console should open up that displays the console log output of the z2 <home> and worker processes - as explained in http://www.z2-environment.eu/check_it_out.

At the first start, the environment will download required resources, which may take a few minutes - depending on your network bandwidth. Subsequent starts will be much quicker. Eventually the server should be up and you can go to the basic admin view at http://localhost:8080/adm (use z* with password z) to verify everything is cool. You do actually not need to start before completing step 3. But checking things are working doesn't hurt either.

Stop the environment again by either pressing Ctrl+C on the console where you started the GUI or by clicking the Exit button on the GUI.

2. Clone the specific sample repository¶

Given the sample repository is called z2-samples.sampleX, go into sample once more and run

git clone -b master http://git.z2-environment.net/z2-samples.sampleX

3. Start¶

Now start the environment again as described above. The environment will now run with the sample configuration and all required dependencies.

In other words: That's it.

Why does that actually work?¶

If you care, here is how everything falls into place:

The z2-base.core repository contains a z2 core installation that is bound to a remote "system repository" at http://git.z2-environment.net/z2-base.base. As it is by now best practice with z2, that repository contains an environment module that describes system specific settings such as other repositories.

By cloning the sample repository you put an override of environment module into view of the dev repository. That is, the local server will take your local definitions with preference over the remote definitions. These may include other remote component repositories such as z2-addons.spring.

In addition the sample repository contains all the modules holding code and other resources that implement the actual sample.

If you already understand how the dev repository works, you will not be surprised to find files called LOCAL in the module folders of cloned repository's workspace.

References¶

• Dev Repository: http://www.z2-environment.eu/v26doc#Workspace%20Development%20Using%20the%20Dev%20Repository