Project

General

Profile

IntelliJ z2 plugin » History » Version 26

Udo Offermann, 21.05.2014 14:02

1 1 Udo Offermann
h1. IntelliJ z2 plugin
2
3
The z2-plugin for IntelliJ IDEA simplifies development with the z2-environment. 
4
The following features are supported as of version 1.0:
5
6 6 Udo Offermann
* *[[IntelliJ_z2_plugin#Launching|Launching]]:* Start your z2-environment on your local machine from the IDE
7 14 Udo Offermann
* *[[IntelliJ_z2_plugin#Managing z2-modules|Managing z2-modules]]:* z2-modules can be created and deleted on demand
8 17 Udo Offermann
* *[[IntelliJ_z2_plugin#Arming modules|Arming modules]]:* Armed z2-modules become active after z2-Sync.
9 10 Udo Offermann
* *[[IntelliJ_z2_plugin#z2-sync|z2-sync]]:* Synchronize your local changes with the z2-environment
10 6 Udo Offermann
* *[[IntelliJ_z2_plugin#z2-dependency-resolution|z2 dependency resolution]]:* Resolve missing dependencies from the z2-environment
11
* *[[IntelliJ_z2_plugin#z2-Module wizard|z2-Module wizard]]:* Create new z2-modules with or without Spring support
12
* *[[IntelliJ_z2_plugin#z2-Properties editor|z2-Properties editor]]:* Provides completions and documentation for z2-properties files
13 1 Udo Offermann
14
h2. Installation
15
16 26 Udo Offermann
In IntelliJ navigate to Preferences -> IDE-Settings -> Plugins and click "Browse repositories". 
17
Type "z2" in the search field of the newly opened popup window and select the z2-environment plugin and
18
click "Download and Install". After the plugin is installed you have to restart the IDE.
19 1 Udo Offermann
20 26 Udo Offermann
21
22 11 Udo Offermann
h2. Prerequisites
23
24 12 Udo Offermann
The IntelliJ z2-plugin requires a certain project layout. The z2-repositories should be checked out directly beneath the project folder
25
(i.e. as siblings of the .idea folder). You have to checkout at least z2-core (e.g. z2-base.core) and the repository containing the modules
26
you want to work with (let's call it "modules"). If you are using Git you must not necessarily clone z2-base.core and z2-addons etc. - 
27
however if you are using subversion it might be easier to check out the whole trunk making it easier to update the sources with one command.
28
29
The important point is that the project structure should look like this:
30
31
<pre>
32
.../my-project
33
     /modules
34
       /my-module-A
35
         ...
36
       /my-web-app-X
37
         ...
38
       /my-web-app-Y
39
         ...
40
     /z2-base.core
41
      ...
42
</pre>
43
44
Where my-module-A and my-web-app-* are arbitrary z2-modules.
45
46
Note that this is slightly different to the Eclipse approach when working with subversion. In Eclipse it's much easier to checkout a project from subversion into
47
the workspace (note the an Eclipse project is more or less on the same level than an IntelliJ module). So in Eclipse you checkout projects and delete them on demand
48
(after you committed your changes). In IntelliJ you _map_ and _unmap_ modules into the IDE which is similar to the Eclipse-Git approach.
49
50
This means that all checked out repositories automatically belong to the z2 dev-repository. Of course their module remain inactive as long as they are unarmed.
51
52 1 Udo Offermann
h2. Preferences
53
54 8 Udo Offermann
The z2-plugin preferences can be found at Project-Settings -> z2-Environment. The typically development settings like host-name=localhost, port=8080, user=z* and password=z are set by default.
55
Once a z2-environment is up and running the settings can be verified using "Test connection...".
56
57
The field "z2 Home Directory" must point to the folder where the z2-core is installed. This location can be chosen by the file picker dialog or by "Search z2-Home" button.
58
The latter one searches the directory structure within your IntelliJ project folder for a valid z2-Home location. The z2-Home location defines which z2-environment will be started when 
59
launching the z2-environment from the IDE.
60
61 1 Udo Offermann
h2. Launching
62
63 9 Udo Offermann
Once the z2-Home is defined, the z2-environment can be launched from the IDE: Select *Tools* -> *Launch z2-environment...*.
64
This will start the z2-environment on your local machine using your local OS JDK (not the one defined in IntelliJ). Beside
65
the standard z2-Swing window the server output is logged inside an IntelliJ tool window (see *View* -> *Tool Windows* -> *z2-environment*).
66
Logs from the z2-server are displayed in red text color while output from the z2-plugin is displayed in blue.
67 1 Udo Offermann
68 14 Udo Offermann
h2. Managing z2-modules
69
70 15 Udo Offermann
Once the project is setup, the required z2-repositories are checked out and the z2-Home setting is defined in the preferences, 
71 16 Udo Offermann
you can create and remove z2-modules on demand. The z2-plugin provides the "Manage z2-module" icon in the IntelliJ toolbar.
72 15 Udo Offermann
It opens a dialog containing a check-box tree with the repositories at the first level and the modules on the second level
73
(additional modules can also occur on the first level). 
74
75 16 Udo Offermann
Now select the modules you want to work on and unselect those you want to get rid off. 
76 15 Udo Offermann
Newly selected modules are displayed in green with a prefixed '+' while modules which are about to be removed are displayed in 
77 16 Udo Offermann
red with a prefixed '-'. When pressing ok the newly selected z2-modules become visible in the IDE as IntelliJ modules with correctly 
78
assigned source folders, while unselected modules are removed from the IDE. Please note that this is just a mapping step, 
79
no files and directories are physically deleted - with one exception: If you open a z2-module in the IDE, work with it and remove it later on, 
80
the initial arming state is restored. So if you open an unarmed z2-module and arm it while working with it while automatically be unarmed when you remove
81 15 Udo Offermann
the module from the IDE by deleting the corresponding LOCAL file.
82 1 Udo Offermann
83 17 Udo Offermann
h2. Arming modules
84 1 Udo Offermann
85 17 Udo Offermann
Modules inside the dev-repository become active once they are armed (which means a file called "LOCAL" exists inside the module folder).
86
Repositories checked out as siblings to z2-base.core belong automatically to the dev-repository. You can arm and disarm modules in IntelliJ 
87
using the context menu in the project view: Right click a module (or any file inside a module) and choose "Arm z2-Module" or "Disarm z2-Module" resp.
88
When multiple modules are selected you can toggle the arming state of each module: "Toggle z2 arming state".
89
90
Arming and disarming has no effect until the z2-environment is synchronized - see next chapter.
91
92 6 Udo Offermann
h2. z2-sync
93 1 Udo Offermann
94 20 Udo Offermann
Clicking !z2_sync.png! in the toolbar or hitting <Alt+Y> triggers a z2-environment synchronization. 
95
z2 checks all(!) repositories for changes and applies them including your local dev-repository as 
96
well as any remote repository. This way your local changes are applied to your z2-instance. Also 
97
changes which have been committed in the meantime to SVN or Git repositories are applied. The set
98
of affected modules are displayed in the balloon notification.
99 17 Udo Offermann
100 1 Udo Offermann
h2. z2 dependency resolution
101 6 Udo Offermann
102 21 Udo Offermann
Clicking !z2_resolve_icon.png! in the toolbar or hitting <Alt+R> triggers a z2-dependency resolution which updates the
103
dependencies of all z2-modules in your IDEa and fixes all dangling references. 
104
Let's assume you have the z2-Modules A & B in your IDE where A depends on B and C (C is a z2-module which is not opened in the IDE, so it's called a remote module).
105
After the z2-refresh the dependencies of A will be fixed: If B is armed A will have a module reference to B
106
and a JAR-reference to C. C's JAR will be downloaded into a special folder called .z2env-lib. If B is not 
107
armed, A will have no module reference but two JAR references to B and C. 
108
109
Note that a z2-dependency resolution includes a z2-sync so that it also displays all affected modules when the operation is done.
110 6 Udo Offermann
111 7 Udo Offermann
h2. z2-Module wizard
112 6 Udo Offermann
113 22 Udo Offermann
TODO
114
115 7 Udo Offermann
h2. z2-Properties editor
116 24 Udo Offermann
117
The IntelliJ z2-plugin provides a completion provider for z2-properties files which
118
supports a subset of z2 property keys and values - e.g. for Java components.
119
On empty z2-properties files only @com.zfabrik.component.type@ and all defined
120
z2-components. This feature works only after a successful z2-dependency resolution.