Project

General

Profile

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

Henning Blohm, 23.10.2021 17:04

1 62 Henning Blohm
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 58 Henning Blohm
You need a z2-base installation as described on the [[How_to_install_z2_v21|previous]] page.
8 64 Henning Blohm
9
Furthermore you need the "Eclipse-IDE":http://www.eclipse.org.
10 4 Udo Offermann
11 27 Henning Blohm
h2. First steps with the z2-Environment
12 1 Udo Offermann
13 60 Henning Blohm
Next, we will look at development for Z2 with Git using Eclipse. Please stop the server before you continue.
14 3 Udo Offermann
15 60 Henning Blohm
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:
16 3 Udo Offermann
17
<pre>
18 58 Henning Blohm
:bin$ cd ../..
19 6 Udo Offermann
:z2-base$ mkdir workspace
20
:z2-base$ ls -l
21
total 0
22
0 drwxr-xr-x   2 mr_x  staff   68  7 Sep 16:34 workspace
23
0 drwxr-xr-x  12 mr_x  staff  408  7 Sep 15:11 z2-base.core
24
:z2-base$
25 1 Udo Offermann
</pre>
26
27 20 Udo Offermann
Now start Eclipse and choose @z2-base/workspace@ as your workspace folder.
28 1 Udo Offermann
29 59 Henning Blohm
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".
30 1 Udo Offermann
31 67 Henning Blohm
*NOTE #1:* On Windows make sure to configure the location of the script as *Working Directory*
32
*NOTE #2:* Make sure to have an appropriate Java home set - if not (see the version check above) you need to adapt the script.
33 66 Henning Blohm
34 59 Henning Blohm
When running you should see a new window labeled "Z2 Home (z2-base)":
35 21 Udo Offermann
36 7 Udo Offermann
!z2_gui.png!
37 12 Udo Offermann
38 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.
39 9 Udo Offermann
40 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. 
41
42 23 Henning Blohm
Other features provided by the Eclipsoid plug-in that are explained in more details on the [[Eclipsoid]] wiki pages.
43 3 Udo Offermann
44 33 Henning Blohm
{{include(how to install eclipsoid)}}
45 21 Udo Offermann
46 13 Udo Offermann
h2. Changing source code and check the result
47 1 Udo Offermann
48 61 Henning Blohm
To change source code, we need a project in Eclipse. Let's change the simple calculator Web application that is contained in the z2-base.base repository. 
49 13 Udo Offermann
50 61 Henning Blohm
To do so, we want to 
51 1 Udo Offermann
52 61 Henning Blohm
# Make the Git repository available in Eclipse's Git tool EGit, 
53
# Import the project into Eclipse and 
54
# Change the project and check the result.
55 48 Henning Blohm
56 61 Henning Blohm
For the first step, open Eclipse's Git perspective and clone the repository at
57 34 Udo Offermann
58 68 Henning Blohm
https://www.z2-environment.net/git/z2-base.base
59 1 Udo Offermann
60
*NOTE:* Make sure it is cloned next to the workspace folder and the z2-base.core folders we created previously. This is because - by default - Z2 is configured to discover changes in locations next to the z2-Home, i.e. the z2-base.core folder.
61 68 Henning Blohm
62
*NOTE:* Check out the branch of the release you are using (e.g. v2.9)
63 49 Henning Blohm
64 61 Henning Blohm
To import the project want to work on into your workspace, import the "com.zfabrik.samples.calculator" from the z2-base.base repository in the Git perspective.
65 49 Henning Blohm
66 26 Henning Blohm
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:
67 34 Udo Offermann
68 1 Udo Offermann
!Calculator_class.png!
69
70 61 Henning Blohm
You will find that the source code is marked 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 !z2_resolve_icon.png! or hit <Alt+R> to trigger a refresh of that build container from your locally running Z2. All red x-markers should be gone by now. 
71 1 Udo Offermann
72 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:
73
74
<pre><code class="java">
75
private enum OP {
76
	CE, C, open, close, 
77
	sqrt, pow, ln, epowx,
78
	sgn, dot, eq, pi, 
79
	add, sub, mult, div, 
80
	sqr, inv, illegal
81
};
82
</code></pre>
83
84
Scroll down to method @doOp()@ and uncomment the section from @case sqrt:@ to @case epowx:@ (line 154 to 170):
85
86
<pre><code class="Java">
87
...
88
	break;
89
90
case sqrt:
91
	new Sqrt().addTo(this.stack);
92
	break;
93
				
94
case pow:
95
	new Pow().addTo(this.stack);
96
	break;
97
98
case ln:
99
	new Ln().addTo(this.stack);
100
	break;
101
				
102
case epowx:
103
	new EPowX().addTo(this.stack);
104
	break;
105
				
106 1 Udo Offermann
default:
107 36 Udo Offermann
...
108 1 Udo Offermann
</code></pre>
109 36 Udo Offermann
110
The implementation classes of these operations do are already exists. 
111
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":
112
113
<pre><code class="html">
114
...
115
<button type="submit" name="op=CE" title="C">CE</button>
116
	
117
<button type="submit" name="op=sqrt" title="r">&radic;</button>
118
<button type="submit" name="op=pow" title="^">x<sup>y</sup></button>
119
<button type="submit" name="op=ln" title="l">ln</button>
120
<button type="submit" name="op=epowx" title="e">e<sup>x</sup></button>
121
				
122
<button type="submit" name="op=pi" title="p">&pi;</button>
123
...
124
</code></pre>
125
126 50 Henning Blohm
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. 
127 1 Udo Offermann
128 61 Henning Blohm
From the Z2 point of view the Eclipse workspace is yet another component repository. We call the implementation the _Dev-Repository_.
129 50 Henning Blohm
130 61 Henning Blohm
Z2 will not consider any arbitrary file system structure noteworthy. Instead to make the inclusion of a specific project into the Dev-Repository effective, we will _arm_ it. This is so that you can choose whether a local workspace version of a module should be considered or rather not. Practically, arming means nothing more elaborate but to put a file called *LOCAL* into the project folder.
131 50 Henning Blohm
132
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.
133
134
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).
135
136
You will see a green "z" decoration at the upper left edge of the Java icon in the package explorer: !green_z_decoration.png!.
137
138
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 !z2_sync.png! or hit <Alt+Y>. 
139
140
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:
141 1 Udo Offermann
142
<pre>
143 17 Udo Offermann
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)
144 39 Udo Offermann
09/28 13:14:47 [36]...hronizationRunner [800]: Found 2 invalidation candidate resources
145
09/28 13:14:47 [36]...hronizationRunner [800]: Invalidated 0 resources
146
09/28 13:14:47 [33]...ent/webWorker@0.2 [800]: 09/28 13:14:47 [19]...stemStateResource [800]: Left system state: environment/webWorkerUp
147
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
148
09/28 13:14:47 [33]...ent/webWorker@0.2 [800]: 09/28 13:14:47 [19]...worker.WorkerSoul [800]: Invalidated 2 resources
149
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
150 17 Udo Offermann
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
151 39 Udo Offermann
09/28 13:14:48 [33]...ent/webWorker@0.2 [800]: 09/28 13:14:48 [19]...stemStateResource [800]: System state attained: environment/webWorkerUp
152 26 Henning Blohm
09/28 13:14:48 [36]...mponentRepository [800]: Overriding module com.zfabrik.samples.calculator: com.zfabrik.dev.repo/devRepo
153 40 Udo Offermann
</pre>
154 51 Henning Blohm
155
Now it's time to check the result: http://localhost:8080/calc - voilà! 
156
157
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!
158
159 63 Henning Blohm
h2. Commit and Share
160
161
Once you have finished, you would normally commit and push your changes. Using the z2-base.base repository that is not such a good idea however.
162
163
But let's assume it was your repository. How would things work from here on, assuming you actually had committed and pushed. 
164
165
In a real-world scenario, your repositories would typically not be local but may be shared with other developers working on the same system. Even if you preferred to have them locally on your development machine, they would not be _in_ your Z2 installation.
166
167
In fact, you would configure additional repositories to be accessed from Z2. After commit and push you could disarm (remove LOCAL) from your local workspace module and at the next synchronization, Z2 would discover the update from the remote repository. 
168
169
Development with Z2 means:
170
171
* Unless you arm local copies of modules, your system is automatically up-to-date with remote sources.
172
* In local repository clones, arm modules you are working on. Modify until satisfied with your changes,
173
* Check frequently by synchronizing and testing,
174
* Commit, push, disarm, synchronize,
175
* Repeat.
176
177
The configuration of further repositories is discussed in [[How_to_create_your_own_system]] and the reference documentation (see below).
178
179 55 Henning Blohm
180 51 Henning Blohm
h2. What's next?
181
182
Please visit the [[Samples]]. In most cases, trying them is straight-forward and instructive.
183
184 53 Henning Blohm
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:
185 1 Udo Offermann
186 65 Henning Blohm
187
188
* {{include(current version)}}
189 53 Henning Blohm
* Check out some of the blogs at [[wiki#blogs|Blogs]]
190 52 Henning Blohm
191
192 54 Henning Blohm
Thanks!
193
194 52 Henning Blohm
---------------------------