Project

General

Profile

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

Henning Blohm, 08.03.2014 22:21

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
(Note: Next time you may of course skip the command line approach and clone the *z2-base.core* repository from within Eclipse.)
35
36 45 Henning Blohm
Next import the z2-base.core project from the repository. Right-click the repository, choose "Import projects..." from the context menu and click "next". If you never started z2 from that installation, you should see only one project called "z2-base.core". Otherwise there may be many. Choose "z2-base.core" (if that's too had to find, uncheck "Search for nested projects"). Click "finish". 
37 43 Henning Blohm
38 44 Henning Blohm
On the Java perspective the "z2-base.core" project should be now available in the package explorer:
39 6 Udo Offermann
40 3 Udo Offermann
!z2_core_project_in_package_explorer.png!
41 7 Udo Offermann
42 45 Henning Blohm
The z2-base.core project contains two launch entries, one for Linux/Mac OS and one for Windows (that is the files with the extension *.launch*). Right click on the launch configuration file that fits to your OS and choose "Run As >" and "z2_base". Alternatively you can go to the External Tools Configuration menu and pick the launch configurations from there.
43 41 Henning Blohm
44 47 Henning Blohm
This starts the z2-environment again and opens the z2-gui inside a new window labeled "Z2 Home (z2-base)":
45 7 Udo Offermann
46
!z2_gui.png!
47 21 Udo Offermann
48 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). 
49 12 Udo Offermann
50 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.
51 9 Udo Offermann
52 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. 
53
54 23 Henning Blohm
Other features provided by the Eclipsoid plug-in that are explained in more details on the [[Eclipsoid]] wiki pages.
55 3 Udo Offermann
56 33 Henning Blohm
{{include(how to install eclipsoid)}}
57 21 Udo Offermann
58 13 Udo Offermann
h2. Changing source code and check the result
59 1 Udo Offermann
60 48 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 base repository. 
61 13 Udo Offermann
62 48 Henning Blohm
To do so, we need to 
63 1 Udo Offermann
64 48 Henning Blohm
# make the Git repository available in Eclipse's Git tool EGit, 
65
# import the project into Eclipse and 
66
# change the project and check the result.
67 1 Udo Offermann
68 48 Henning Blohm
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:
69
70
In the new "z2-environment" menu choose the entry labled "z2-Repositories view".
71
72 1 Udo Offermann
This will open a view like this:
73 14 Udo Offermann
74 1 Udo Offermann
!z2-Repositories-view.png!
75
76 47 Henning Blohm
This view lists all repositories currently known by the running system. 
77 1 Udo Offermann
78 48 Henning Blohm
(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).
79 47 Henning Blohm
80 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.
81 1 Udo Offermann
82 49 Henning Blohm
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. 
83 1 Udo Offermann
84 49 Henning Blohm
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. 
85
86
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 
87
88 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:
89 34 Udo Offermann
90 1 Udo Offermann
!Calculator_class.png!
91
92 49 Henning Blohm
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 !z2_resolve_icon.png! or hit <Alt+R> to trigger a refresh of that build container. All red x-markers should be gone by now. 
93 1 Udo Offermann
94 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:
95
96
<pre><code class="java">
97
private enum OP {
98
	CE, C, open, close, 
99
	sqrt, pow, ln, epowx,
100
	sgn, dot, eq, pi, 
101
	add, sub, mult, div, 
102
	sqr, inv, illegal
103
};
104
</code></pre>
105
106
Scroll down to method @doOp()@ and uncomment the section from @case sqrt:@ to @case epowx:@ (line 154 to 170):
107
108
<pre><code class="Java">
109
...
110
	break;
111
112
case sqrt:
113
	new Sqrt().addTo(this.stack);
114
	break;
115
				
116
case pow:
117
	new Pow().addTo(this.stack);
118
	break;
119
120
case ln:
121
	new Ln().addTo(this.stack);
122
	break;
123
				
124
case epowx:
125
	new EPowX().addTo(this.stack);
126
	break;
127
				
128
default:
129
...
130
</code></pre>
131
132
The implementation classes of these operations do are already exists. 
133
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":
134
135
<pre><code class="html">
136
...
137
<button type="submit" name="op=CE" title="C">CE</button>
138
	
139
<button type="submit" name="op=sqrt" title="r">&radic;</button>
140
<button type="submit" name="op=pow" title="^">x<sup>y</sup></button>
141
<button type="submit" name="op=ln" title="l">ln</button>
142
<button type="submit" name="op=epowx" title="e">e<sup>x</sup></button>
143
				
144
<button type="submit" name="op=pi" title="p">&pi;</button>
145
...
146
</code></pre>
147
148 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. 
149 1 Udo Offermann
150 50 Henning Blohm
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.
151
152
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.
153
154
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.
155
156
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).
157
158
You will see a green "z" decoration at the upper left edge of the Java icon in the package explorer: !green_z_decoration.png!.
159
160
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>. 
161
162
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:
163 1 Udo Offermann
164 17 Udo Offermann
<pre>
165 39 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)
166
09/28 13:14:47 [36]...hronizationRunner [800]: Found 2 invalidation candidate resources
167
09/28 13:14:47 [36]...hronizationRunner [800]: Invalidated 0 resources
168
09/28 13:14:47 [33]...ent/webWorker@0.2 [800]: 09/28 13:14:47 [19]...stemStateResource [800]: Left system state: environment/webWorkerUp
169
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
170
09/28 13:14:47 [33]...ent/webWorker@0.2 [800]: 09/28 13:14:47 [19]...worker.WorkerSoul [800]: Invalidated 2 resources
171
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
172
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
173
09/28 13:14:48 [33]...ent/webWorker@0.2 [800]: 09/28 13:14:48 [19]...stemStateResource [800]: System state attained: environment/webWorkerUp
174
09/28 13:14:48 [36]...mponentRepository [800]: Overriding module com.zfabrik.samples.calculator: com.zfabrik.dev.repo/devRepo
175 17 Udo Offermann
</pre>
176
177 39 Udo Offermann
Now it's time to check the result: http://localhost:8080/calc - voilà! 
178 26 Henning Blohm
179 40 Udo Offermann
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!
180 51 Henning Blohm
181
182
h2. What's next?
183
184
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
185
186
* [[Step 4 - First steps with Z2 on SVN]]
187
* [[Repositories]]
188
189
Please visit the [[Samples]]. In most cases, trying them is straight-forward and instructive.
190
191 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:
192 1 Udo Offermann
193 53 Henning Blohm
* Start reading the "v2.2 documentation":http://www.z2-environment.eu/v22doc
194
* Check out some of the blogs at [[wiki#blogs|Blogs]]
195 52 Henning Blohm
196
197 54 Henning Blohm
Thanks!
198
199 52 Henning Blohm
---------------------------