1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<LINK REL="STYLESHEET" HREF="../../book.css" TYPE="text/css">
<title>Creating a Subsystem Configuration</title>
</head>
<body bgcolor="#ffffff">
<h1>Creating a Subsystem Configuration</h1>
<p>In this tutorial, you will use the RSE <A href="../../reference/extension-points/org_eclipse_rse_ui_subsystemConfiguration.html">subsystemConfiguration extension point</A> to show new subsystems within connections, when they are expanded. Effectively,
you will add a new <i>remote-accessing tool</i> to the Remote System Explorer.</p>
<p>
A full-blown tutorial to illustrate this extension point is a bit difficult without inventing
server-side code and a communication layer for that server-side code to communication with the
client-side subsystem. Rather than becoming bogged down in these details, this tutorial will not
write server-side code or a communications-layer, but instead will hard-code the remote resources
on the client-side so as to focus discussion on the client-side code. The extension point assumes
you already have server-side code and a communication layer you now want to exploit within
Eclipse.
</p>
<h2>Scenario</h2>
<p>This tutorial pretends that you have server-side code, which manages user profiles for developers, and
<i>teams</i> of developers. There is a master list of developers identified for development access
to this server, and there is a grouping mechanism that allows developers to be assigned to named
teams. Developers may exist on multiple teams. Each developer can have one or more <i>roles</i>, which
may affect what they are allowed to access.</p>
<p>In this tutorial you will define a subsystem for working with these resources in the remote system
identified by the parent connection object. This will first list teams, then developers within teams.
Roles will be accessible via an action.
</p>
<p><i>Do not worry about how useful or realistic the example is. The point of the exercise is
show the code necessary to fully enable new subsystems. It is up to the subsystem developer to
decide what resources to expose and what actions on those resources.</i></p>
<br>
<hr>
<h2>Step By Step: Creating a Subsystem Configuration</h2>
<p>If you have not already, first <a href="pdeProject.html">create or prepare a plugin project</a>
We will follow the steps listed in the <A href="../plugin/subsystem.html#steps">Overview of Steps</A> section in the description of the plugin.</p>
<ol>
<li>Create a package named <samp><b>samples.subsystems</b></samp>, by right-clicking on the <samp>src</samp> folder
and using the <b>New->Package</b> wizard. In the new package, create an empty interface named <A href="IDeveloperSubSystem.html"><samp>IDeveloperSubSystem</samp></A>, by right-clicking on the package and selecting <b>New->Interface</b>.
</li>
<li>Also in package <samp>samples.subsystems</samp>, use <b>New->Class</b> to
create a class named <samp><b>DeveloperConnectorService</b></samp> that extends <b>superclass</b>
<samp><A href="../../reference/api/org/eclipse/rse/core/subsystems/AbstractConnectorService.html">AbstractConnectorService</A></samp>,
selecting the option to include <b>Constructors from superclass</b>. Edit the result to add
a <samp>connected</samp> instance variable that is used in the methods, as shown in bold <a href="DeveloperSystem.html">here</a>.
</li>
<li>Again in package <samp>samples.subsystems</samp>, use <b>New->Class</b> to
create a class named <samp><b>DeveloperSystemManager</b></samp> that extends <b>superclass</b>
<samp><A href="../../reference/api/org/eclipse/rse/core/subsystems/AbstractConnectorServiceManager.html">AbstractSystemManager</A></samp>,
selecting the option to include <b>Constructors from superclass</b>. Edit the result to add
a factory method, and flesh out the methods, as highlighted <a href="DeveloperSystemManager.html">here</a>.
</li>
<li>Create a package named <samp><b>samples.model</b></samp>. Create two classes in it:
<b><samp>TeamResource</samp></b> and <b><samp>DeveloperResource</samp></b>, each of which extend
<A href="../../reference/api/org/eclipse/rse/core/subsystems/AbstractResource.html">AbstractResource</A>.
<ol>
<li type="i">Edit <samp>DeveloperResource</samp> to add <samp>name</samp>, <samp>id</samp>, and <samp>deptNbr</samp> properties, as shown in bold <a href="DeveloperResource.html">here</a>.<li type="i">Edit <samp>TeamResource</samp> to add <samp>name</samp> and <samp>developers</samp> (array) properties,
as shown in bold <a href="TeamResource.html">here</a>.
</ol>
<li>You need to think about filter support. For now, you can keep it simple: users can only create filters that list teams,
by specifying a single string that is either a scalar or a generic team name. If scalar, one team will be shown when the filter is expanded.
If generic, all teams matching the generic pattern will be listed. Given the simplicity, you will not need to create a filter string class to perform
parsing. As a result, you have nothing to do for this step.</li>
<li>Return to package <samp>samples.subsystems</samp>, and create class <b><samp>DeveloperSubSystem</samp></b>
that extends <samp><A href="../../reference/api/org/eclipse/rse/core/subsystems/SubSystem.html">SubSystem</A></samp>.
Edit the generated class to add code highlighted <a href="DeveloperSubSystem.html">here</a>.</li>
<li>Again in package <samp>samples.subsystems</samp>, create class <b><samp>DeveloperSubSystemFactory</samp></b>
that extends <samp><A href="../../reference/api/org/eclipse/rse/core/subsystems/SubSystemConfiguration.html">SubSystemConfiguration</A></samp>.
Edit the generated class to add code highlighted <a href="DeveloperSubSystemFactory.html">here</a>.
</li>
<li>In the project's root folder, find and edit file <samp>rseSamplesResources.properties</samp> and
add the line highlighted <a href="rseSamplesResources3.html">here</a>.
</li>
<li>Update your <samp>plugin.xml</samp> file to include the following lines:
<pre><samp>
<!-- ======================================= -->
<!-- SubSystem Configuration -->
<!-- ======================================= -->
<extension point="org.eclipse.rse.ui.subsystemConfiguration">
<configuration
id="samples.subsystems.factory"
systemtypes="Linux;Unix;Windows"
name="Teams"
class="samples.subsystems.DeveloperSubSystemConfiguration"
category="users"
vendor="ACME"
>
</configuration>
</extension>
</samp></pre>
<b>Note:</b> You would normal use the <samp>icon</samp> and <samp>iconLive</samp> attributes to specify
a unique icon for your subsystem, but to keep it simple here, just use the default icon.
</li>
</ol>
<p>Now you are far enough along that you can try our what you have, before proceeding. Select
<b>Run->Run As->Run-time workbench</b>. Create a new Linux connection in the RSE, and
expand it. You'll now see your <A href="runIt1.gif">new subsystem</A>, which you can expand
to see its default filter, which in turn you can expand to see your hardcoded list of teams:<br>
<IMG border="0" src="runIt1.gif" width="800" height="514">
<br>
You will be prompted for a user ID and password, but since the system class does not really
connect, enter anything you like!
<p>Eventually, you will be able to expand a team to see its developers.</p>
<p>Now it is time to work on the appearance and functions of those remote resources. You will do this
by creating adapters for the resources:</p>
<ol start="10">
<li>Select the <samp>samples.model</samp> package, and:
<ol>
<li type="i">Create a new class named <samp>TeamResourceAdapter</samp> that extends <a href="../../reference/api/org/eclipse/rse/ui/view/AbstractSystemViewAdapter.html"><samp>AbstractSystemViewAdapter</samp></A> and implements
<a href="../../reference/api/org/eclipse/rse/ui/view/ISystemRemoteElementAdapter.html"><samp>ISystemRemoteElementAdapter</samp></A>.
Edit the generated class and add the code highlighted <a href="TeamResourceAdapter.html"><b>here</b></a>.
</li>
<li type="i">Create a new class named <b><samp>DeveloperResourceAdapter</samp></b>
that extends <a href="../../reference/api/org/eclipse/rse/ui/view/AbstractSystemViewAdapter.html"><samp>AbstractSystemViewAdapter</samp></a> and implements
<a href="../../reference/api/org/eclipse/rse/ui/view/ISystemRemoteElementAdapter.html"><samp>ISystemRemoteElementAdapter</samp></A>.
Edit the generated class and add the code highlighted <a href="DeveloperResourceAdapter.html"><b>here</b></a>.
</li>
<li type="i">Next, you need the icons for your remote resources, which you referred to in your adapters. Edit the <samp>RSESamplesPlugin</samp> file and edit the <samp>initializeImageRegistry</samp>
to add the lines of code highlighted <a href="InitializeImageRegistry.html"><b>here</b></a>. Now, you need the icons. Select the <samp>RSESamplesPlugin</samp> project, right-click and select <b>New->Folder</b> and create a folder named <b>icons</b>. Select the new folder, and use <b>File->Import</b> to
import the <samp>team.gif</samp> and <samp>developer.gif</samp> files from the <samp>org.eclipse.rse.examples.tutorial/icons</samp> folder.</li>
</ol>
</li>
<li>Creating the adapters does nothing until you register them with the platform. To do that, you need
an adapter factory class and you need to register it with the platform:
<ol>
<li type="i">Select the <samp>samples.model</samp> package and in it create a class named
<b>DeveloperAdapterFactory</b> that extends <samp><a href="../../reference/api/org/eclipse/rse/ui/view/AbstractSystemRemoteAdapterFactory.html">AbstractSystemRemoteAdapterFactory</a></samp>
and implements interface <samp><b>org.eclipse.core.runtime.IAdapterFactory</b></samp>.
Edit the generate class as per the highlighted code <a href="DeveloperAdapterFactory.html"><b>here</b></a>.
</li>
<li type="i">Back in the <samp>RSESamplesPlugin</samp> class, add the highlighted code
<b><a href="startup.html">here</a></b> to your <samp>startup</samp> method.
</li>
</ol>
</li>
</ol>
<p>Once again, run the workbench to see your new subsystem:<br>
<IMG border="0" src="runIt2.gif" width="886" height="594"><br>
It is looking better now! There are icons and labels, and the team resources are expandable. Try the following things with
your new subsystem resources:</p>
<ul>
<li>Right-click on <samp>Team 1</samp> and select the <a href="renameAction.gif">rename action</A>. The rename action is enabled because you
overwrote <a href="TeamResourceAdapter.html#canRename">canRename</a> in the team resource adapter class. Try renaming it to a name already in use.
The <a href="renameDialog.gif">rename dialog</a> can catch this error because we returned the list of names in use in
the <a href="TeamResourceAdapter.html#getNames">getRemoteParentNamesInUse</a>
method in our team resource adapter class. Rename to a new name. The rename in fact happens because we implemented
the <a href="TeamResourceAdapter.html#doRename">doRename</a> method.
<li>The default filter <samp>All teams</samp> exists because we wrote code to create it in
our <a href="DeveloperSubSystemFactory.html#createDefaultFilterPool">createDefaultFilterPool</a>
subsystem factory method. Try creating a new filter: right-click on <samp>Teams</samp> subsystem and select
<a href="newFilterAction.gif">New->Filter</a> to get the
<a href="NewFilterWizard.gif">New Filter wizard</a>. Enter <samp>*2</samp>, press <b>Next</b>, and
enter <samp>Test filter</samp> for the filter name. Press <b>Finish</b>
to create the filter. Expand it, and you will see that only teams whose name ends with "2" are shown:<br>
<IMG border="0" src="testFilter.gif">
<br>
Filter support is free in the RSE,
but you do have to write our own code to apply that filter pattern as you see fit. In this case, we did this in our
<a href="DeveloperSubSystem.html#resolveFilterString">internalResolveFilterString</a> subsystem method.
<li>Notice how a resource like team can display multiple times, by different filters that resolve to it.
Rename <samp>Team 2</samp> shown under the new expanded <samp>Test filter</samp>, and notice how it is successfully
renamed under both filters. This ability to refresh the name in all occurrences of the same resource is made
possible by the adapter methods <a href="TeamResourceAdapter.html#getAbsoluteName">getAbsoluteName</a>, which helps
RSE find redundant copies of the same object, and <a href="TeamResourceAdapter.html#refreshRemoteObject">refreshRemoteObject</a>,
which the RSE calls, on each redundant copy, on a rename operation.
<IMG border="0" src="testRename.gif"></ul>
<p>
<br><br><br>
<p>There are no steps to perform here, but for your reference here is some information on how to further
evolve the functions via your adapter, should you want to:</p>
<ul>
<li>To not show the rename and delete actions at all, or to enable them,
override appropriate methods in the adapter class. For details see the methods
<A href="../../reference/api/org/eclipse/rse/ui/view/AbstractSystemViewAdapter.html#showRename(java.lang.Object)">showRename</A>,
<A href="../../reference/api/org/eclipse/rse/ui/view/AbstractSystemViewAdapter.html#showDelete(java.lang.Object)">showDelete</A>,
<A href="../../reference/api/org/eclipse/rse/ui/view/AbstractSystemViewAdapter.html#doRename(org.eclipse.swt.widgets.Shell, java.lang.Object, java.lang.String)">doRename</A>
and
<A href="../../reference/api/org/eclipse/rse/ui/view/AbstractSystemViewAdapter.html#doDelete(org.eclipse.swt.widgets.Shell, java.lang.Object)">doDelete</A> in the parent
<samp><A href="../../reference/api/org/eclipse/rse/ui/view/AbstractSystemViewAdapter.html">AbstractSystemViewAdapter</A></samp> class.
<li>To supply your own validator for syntax checking of new names on the rename dialogs,
override <A href="../../reference/api/org/eclipse/rse/ui/view/AbstractSystemViewAdapter.html#getNameValidator(java.lang.Object)">getNameValidator</A>.
<li>To add additional actions to the pop-up menus, implement the <A href="../../reference/api/org/eclipse/rse/ui/view/AbstractSystemViewAdapter.html#addActions(com.ibm.etools.systems.core.ui.SystemMenuManager, org.eclipse.jface.viewers.IStructuredSelection, org.eclipse.swt.widgets.Shell, java.lang.String)">addActions</a>
method in your adapter class.
<li>To support dragging and dropping, override the
<A href="../../reference/api/org/eclipse/rse/ui/view/AbstractSystemViewAdapter.html#canDrag(java.lang.Object)">canDrag</a> and
<A href="../../reference/api/org/eclipse/rse/ui/view/AbstractSystemViewAdapter.html#canDrop(java.lang.Object)">canDrop</a> parent methods in your adapter class.
<li>To add additional properties to the property sheet, implement the
<A href="../../reference/api/org/eclipse/rse/ui/view/AbstractSystemViewAdapter.html#internalGetPropertyDescriptors()">internalGetPropertyDescriptors</a> and
<A href="../../reference/api/org/eclipse/rse/ui/view/AbstractSystemViewAdapter.html#internalGetPropertyValue()">internalGetPropertyValue</a> methods
in your adapter class.
<li>To add property pages to your remote objects (the Properties popup menu item will then appear) use
the RSE <A href="../plugin/propertypage.html">propertyPages</a> extension point.
</ul>
<br><br><br>
<p>Now you will continue with the tutorial by enhancing the running example to supply its own actions for creating and changing
filters. You will support two types of filters in our subsystems: team filters and developer filters. You have seen team filter already,
but developer filters will be new. They will contain a team name and a developer name-pattern, and when expanded, they will list all the
matching developers in the given team. The filter string syntax for developer filters will be "team-name/developer-generic-name". Because
you have more than one type of filter, our filter wizards will set the type attribute for the filters, so the change action will know
which dialog to present to the user. This will also allow you to have different icons for each filter.
<ol start="11">
<li>Follow these steps to enable support for our own filter-support:
<ol>
<li type="i">First, create the new GUI pane for your developer filter prompts. Select the <samp>samples.subsystems</samp>
package and in it create a new class named <samp><b>DeveloperFilterStringEditPane</b></samp> that extends the
class <samp><b>SystemFilterStringEditPane</b></samp> in package <samp>com.ibm.etools.systems.filters.ui</samp>.
Edit the new class, adding the code highlighted <a href="DeveloperFilterStringEditPane.html">here</a>.
</li>
<li type="i">Edit the <samp>DeveloperSubSystemFactory</samp> class, and add the code highlighted
<a href="DeveloperSubSystemFactory2.html">here</a>.
</li>
<li type="i">Next, you need the unique icons for your own filters, which you referred to in your subsystem factory. Edit the <samp>RSESamplesPlugin</samp> file and edit the <samp>initializeImageRegistry</samp>
to add the lines of code highlighted <a href="InitializeImageRegistry2.html">here</a>. Now you need these icons.
Select the folder named <b>icons</b> and use <b>File->Import</b> to
import the <samp>teamFilter.gif</samp> and <samp>developerFilter.gif</samp> files from the
<samp>plugins\com.ibm.etools.systems.doc.isv\icons</samp> folder,
typically found in <samp>c:\wdsc\iseries</samp> where c:\wdsc is where you installed this product.
</li>
<li type="i">Now you need to edit your subsystem so it will parse the two types of filters you now
have. Edit <samp>DeveloperSubSystem</samp> and edit it as highlighted <a href="DeveloperSubSystem2.html#resolve">here</a>.
</li>
<li type="i">In the project's root folder, find and edit file <samp>rseSamplesResources.properties</samp> and
add the line highlighted <a href="rseSamplesResources4.html">here</a>.
</li>
<li type="i">Now you can run again. Right click on the <samp>Teams</samp> subsystem, to see the new actions for
creating filters:<br>
<IMG border="0" src="NewFilterActions.gif">
<IMG border="0" src="TeamFilterWizard.gif"><br><br>
<IMG border="0" src="DeveloperFilterWizard.gif"><br><br>
Create a team filter and a developer filter, and notice the new icons:<br>
<IMG border="0" src="NewFilterIcons.gif"><br><br>
Now right-click on a team filter and select Change, and then do the same for a developer filter:<br>
<IMG border="0" src="TeamFilterDialog.gif">
<IMG border="0" src="DeveloperFilterDialog.gif"><br>
</li>
</ol>
</li>
</ol>
<br><br><br>
</body>
</html>
|
