Project

General

Profile

Step 3 - First steps with Z2 on Git » History » Version 37

Udo Offermann, 28.09.2012 13:08

1 29 Udo Offermann
h1. First steps with Z2 on Git
2 1 Udo Offermann
3 32 Udo Offermann
[[Step_2_-_Install_and_run_in_5_minutes|« Step 2 - Install and run in 5 minutes]]
4 1 Udo Offermann
5 4 Udo Offermann
h2. Prerequisites
6
7
You need a cloned z2-base.core repository as described on the [[How_to_install_z2_v21|previous]] page.
8 13 Udo Offermann
Furthermore you need the "Eclipse-IDE":http://www.eclipse.org (one of Galileo, Helios, Indigo or Juno is fine) and the "Egit plug-in:":http://www.eclipse.org/egit. 
9 4 Udo Offermann
10 27 Henning Blohm
h2. First steps with the z2-Environment
11 1 Udo Offermann
12 30 Udo Offermann
Next, we will look at the steps to development for Z2 with Git using Eclipse. Please stop the server before you continue.
13 3 Udo Offermann
14 22 Henning Blohm
In order to have modules from local 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 still inside the "run/bin" directory) and create a folder called "workspace" - this will be used as the workspace root for Eclipse:
15 3 Udo Offermann
16
<pre>
17 6 Udo Offermann
:bin$ cd ../../..
18
:z2-base$ mkdir workspace
19
:z2-base$ ls -l
20
total 0
21
0 drwxr-xr-x   2 mr_x  staff   68  7 Sep 16:34 workspace
22
0 drwxr-xr-x  12 mr_x  staff  408  7 Sep 15:11 z2-base.core
23
:z2-base$
24 1 Udo Offermann
</pre>
25
26 20 Udo Offermann
Now start Eclipse and choose @z2-base/workspace@ as your workspace folder.
27 1 Udo Offermann
28 22 Henning Blohm
We will add the core repository to the EGit repositories view. Detailed documentation on how to work with EGit can be found on the "EGit Wiki pages":http://wiki.eclipse.org/EGit/User_Guide.
29
In the Git perspective choose "Add an existing local Git repository". In the "Directory" field type in the path to the ".../z2-base" directory. 
30
After hitting "search" the search results should list the *z2-base.core* repository, click "finish" and the repositories view should look like this:
31 1 Udo Offermann
32 6 Udo Offermann
!EGit_repo_view_with_z2-core.png!
33 1 Udo Offermann
34 22 Henning Blohm
35
(Note: Next time you may of course skip the command line approach and clone the *z2-base.core* repository from within Eclipse.)
36
37 27 Henning Blohm
Next import the core project from the repository. Right-click the repository, choose "Import projects..." from the context menu and click "next" and then "finish". 
38 6 Udo Offermann
On the Java perspective the "core" project should be now available in the package explorer:
39
40 3 Udo Offermann
!z2_core_project_in_package_explorer.png!
41 7 Udo Offermann
42 1 Udo Offermann
The core project contains two launch entries, one for Linux/Mac OS and one for Windows. Right click the one that fits to your OS and choose "Run As >" and "z2_base".
43 22 Henning Blohm
This starts the z2-environment again and opens the z2-gui inside a new window labeled "Z2 Home (z2-base v2.1)":
44 7 Udo Offermann
45
!z2_gui.png!
46 21 Udo Offermann
47 7 Udo Offermann
From now on you will find the z2-base launch entries in Eclipse "External Tools" (either inside "Run", "External Tools >" or click the "External Tools" button in the toolbar). 
48 12 Udo Offermann
49 23 Henning Blohm
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.
50 9 Udo Offermann
51 24 Henning Blohm
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. 
52
53 23 Henning Blohm
Other features provided by the Eclipsoid plug-in that are explained in more details on the [[Eclipsoid]] wiki pages.
54 3 Udo Offermann
55 33 Henning Blohm
{{include(how to install eclipsoid)}}
56 21 Udo Offermann
57 13 Udo Offermann
h2. Changing source code and check the result
58 1 Udo Offermann
59 26 Henning Blohm
To change source code, we need a project in Eclipse. Let's change the hello-world Web application that is contained in the samples repository. 
60 13 Udo Offermann
61 26 Henning Blohm
To do so, we need to a) make the Git repository available in EGit, b) import the project into Eclipse and c) change the project and check the result.
62
63 1 Udo Offermann
The Eclipsoid plug-in simplifies these steps. Since the z2-environment knows the repository landscape, we can ask it to share this knowledge with us. In the new "z2-environment" menu choose the entry labled "z2-Repositories view".
64 26 Henning Blohm
65 1 Udo Offermann
This will open a view like this:
66
67 14 Udo Offermann
!z2-Repositories-view.png!
68 1 Udo Offermann
69 36 Udo Offermann
This view lists all repositories known by the running system. The Eclipsoid plug-in connects by default to the Eclipsoid Web application on http://localhost:8080/eclipsoid/z2info that provides online information about the running environment. Note that the connection can be customized on the "z2-environment" preference page.
70 14 Udo Offermann
71 34 Udo Offermann
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.
72 1 Udo Offermann
73 34 Udo Offermann
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 core repository inside your z2-base directory. You can check this by double clicking on the base repository entry (note that it now looks like a hyperlink with blue text color). Switch back to the Java perspective 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 - without switching the perspectives.
74 14 Udo Offermann
75 34 Udo Offermann
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:
76 26 Henning Blohm
77 34 Udo Offermann
!Calculator_class.png!
78 1 Udo Offermann
79 35 Udo Offermann
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. Either select the entry "Resolve z2-Project classpaths", click the new icon !z2_resolve_icon.png!, or simply hit <Alt+R> to trigger a refresh of that build container. All red x-markers should be gone by now. 
80 1 Udo Offermann
81 36 Udo Offermann
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:
82
83
<pre><code class="java">
84
private enum OP {
85
	CE, C, open, close, 
86
	sqrt, pow, ln, epowx,
87
	sgn, dot, eq, pi, 
88
	add, sub, mult, div, 
89
	sqr, inv, illegal
90
};
91
</code></pre>
92
93
Scroll down to method @doOp()@ and uncomment the section from @case sqrt:@ to @case epowx:@ (line 154 to 170):
94
95
<pre><code class="Java">
96
...
97
	break;
98
99
case sqrt:
100
	new Sqrt().addTo(this.stack);
101
	break;
102
				
103
case pow:
104
	new Pow().addTo(this.stack);
105
	break;
106
107
case ln:
108
	new Ln().addTo(this.stack);
109
	break;
110
				
111
case epowx:
112
	new EPowX().addTo(this.stack);
113
	break;
114
				
115
default:
116
...
117
</code></pre>
118
119
The implementation classes of these operations do are already exists. 
120
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":
121
122
<pre><code class="html">
123
...
124
<button type="submit" name="op=CE" title="C">CE</button>
125
	
126
<button type="submit" name="op=sqrt" title="r">&radic;</button>
127
<button type="submit" name="op=pow" title="^">x<sup>y</sup></button>
128
<button type="submit" name="op=ln" title="l">ln</button>
129
<button type="submit" name="op=epowx" title="e">e<sup>x</sup></button>
130
				
131
<button type="submit" name="op=pi" title="p">&pi;</button>
132
...
133
</code></pre>
134
135 37 Udo Offermann
To make our changes effective on the running environment, we have to tell the server two things: Firstly that it should check for changed source code and secondly that it should - beside all connected Git repositories - consider our local version as well. From the Z2 point of view the Eclipse workspace is a repository too! We call it the _Dev-repository_ because it contains the latest ongoing development. 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 *com.zfabrik.boot.config/baseRepository* and one inside the Dev-repository which is mapped to the Eclipse workspace. So which one should it take? To solve this "conflict" the Dev-repository has a switch for each project which can be "armed" and "disarmed". If it is "disarmed" - which is the default - the version in the repository will win. If it's "armed" our version in the workspace will win. So we need to "arm" the calculator project: Right-click the project "com.zfabrik.samples.calculator" in the Java Package Explorer and choose "Arm z2-Projects".
136 16 Udo Offermann
137 26 Henning Blohm
You will notice that there is now a green "z" decoration at the upper left edge of the Java icon in the package explorer: !green_z_decoration.png!.
138
After we specified that the workspace version of the Hello World 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 !z2_sync.png!, or simply hit <Alt+Y>. You can also switch to the z2-gui and click the "Sync" button. As described before, the Eclipsoid plug-in talks to the z2 server via http. In situations where the web server cannot be started, the Eclipsoid web applicaton 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:
139 1 Udo Offermann
140 17 Udo Offermann
<pre>
141 1 Udo Offermann
09/11 15:34:54 [34]...entRepositoryImpl[800]: Pulled deltas from GitCR environment/samplesRepository (origin=http://git.z2-environment.net/z2-base.samples, branch=v2.1, OPTIONAL)  within 56msec
142
09/11 15:34:54 [34]...entRepositoryImpl[800]: Pulled deltas from GitCR com.zfabrik.boot.config/systemRepository (origin=http://git.z2-environment.net/z2-base.base, branch=v2.1)  within 29msec
143 17 Udo Offermann
09/11 15:34:54 [34]...hronizationRunner[800]: Found 1 invalidation candidate resources
144
09/11 15:34:54 [34]...hronizationRunner[800]: Invalidated 0 resources
145
09/11 15:34:54 [31]...ent/webWorker@0.2[800]: 09/11 15:34:54 [19]...stemStateResource[800]: Left system state: environment/webWorkerUp
146
09/11 15:34:54 [31]...ent/webWorker@0.2[800]: 09/11 15:34:54 [19]...pp.WebAppResource[800]: Stopping Web App (/helloworld): com.zfabrik.samples.helloworld/web
147
09/11 15:34:54 [31]...ent/webWorker@0.2[800]: 09/11 15:34:54 [19]...worker.WorkerSoul[800]: Invalidated 1 resources
148
09/11 15:34:54 [31]...ent/webWorker@0.2[800]: 09/11 15:34:54 [19]...pp.WebAppResource[800]: Starting WebApp: com.zfabrik.samples.helloworld/web
149
09/11 15:34:55 [31]...ent/webWorker@0.2[800]: 09/11 15:34:55 [19]...pp.WebAppResource[800]: Done starting Web App (/helloworld): com.zfabrik.samples.helloworld/web
150
09/11 15:34:55 [31]...ent/webWorker@0.2[800]: 09/11 15:34:55 [19]...stemStateResource[800]: System state attained: environment/webWorkerUp
151
09/11 15:34:55 [34]...entRepositoryImpl[800]: Pulled deltas from GitCR com.zfabrik.boot.config/systemRepository (origin=http://git.z2-environment.net/z2-base.base, branch=v2.1)  within 29msec
152
09/11 15:34:55 [34]...entRepositoryImpl[800]: Pulled deltas from GitCR environment/samplesRepository (origin=http://git.z2-environment.net/z2-base.samples, branch=v2.1, OPTIONAL)  within 30msec
153
</pre>
154
155 2 Udo Offermann
Now it's time to check the result: http://localhost:8080/helloworld - voilà! 
156 26 Henning Blohm
157
Please repeat these steps a few times: Change the source code, hit <Alt+Y> and check the result, so you will get a feeling of how fast developement roundtrips can be!