-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.txt
258 lines (222 loc) · 13.7 KB
/
README.txt
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
# Rainbow Adaptation Integrated Development Environment (RAIDE) SDK ReadMe file.
#
# Author: Shang-Wen Cheng ([email protected])
# Phone: 626-689-2891
# Skype: zenoolon
#
# RAIDE SDK content copyright Carnegie Mellon University (C) 2006-2009.
# All rights reserved.
#
# History:
# - [SWC 2009.12.19] Refreshed file content.
# - [SWC 2007.04.05] Created file
== Overview ==
Please refer to the "Directory Structure" section to get a quick overview of the
content within the Rainbow Translator Contributor SDK Eclipse workspace.
Minimum System Requirements:
Java SDK 1.5 or 1.6
Eclipse SDK 3.2+
Subclipse plug-in 1.2+ (in order to access this content from repository)
Rainbow Toolkit plug-in 1.2+ (for Rainbow Stitch script editing)
[Recommended] AcmeStudio 3.4+ (for editing Acme architecture model)
This SDK has been set up to facilitate customization of the Rainbow framework
to a "target system", particularly the development of custom Probes, Gauges, and
Effectors. The SDK JAR provides common interface and abstract parent classes
for the Rainbow framework constructs, including Probe, Gauges, and Effectors.
Sources are included in the SDK JAR for convenient reference, so please kindly
DO NOT distribute or deploy this software outside your specific project for
which we have released to you this SDK.
To execute Rainbow, deployment files can be generated by the build script, as
explained in the "Build Instructions" section. Once deployed, invoke Rainbow
as explained in the section "Deployment and Invocation Instructions".
-- Meeting the System Requirements --
* Java SDK (J2SE) 1.5/1.6
Download and install from http://java.sun.com/javase/downloads/index_jdk5.jsp
* Eclipse SDK 3.2+
Download and install from http://www.eclipse.org/downloads/
* Subclipse 1.2+ (requires Eclipse)
Once you've downloaded Eclipse 3.2.x, choose from the menu Help -> Software
Updates -> Find and Install... Choose "Search for new features to install".
Then add "Subclipse update site" as "New Remote Site..." and point to the URL
http://subclipse.tigris.org/update_1.2.x ; checkbox it and click [Finish],
then download and install the most recent version according to dialog prompt.
* Rainbow Toolkit 1.2+ (requires Eclipse)
Use Eclipse Software Updates; add "Rainbow Toolkit" as "New Remote Site..."
and point to the URL http://waterfall.able.cs.cmu.edu/rainbow/update ;
checkbox it and click [Finish], then download and install the most recent
version according to dialog prompt.
* AcmeStudio 3.4 (requires Eclipse)
Register a download account: http://acme.able.cs.cmu.edu/acmeweb/download.php
Then follow instructions to configure the Eclipse Update Manager to download
AcmeStudio. You may choose to use the Release, Stable, or Nightly version.
-- Customizing the "Translators" --
Probes:
A Probe is a piece of code that regularly reports some state information of
the target system, and is either inserted into the target system codebase, or
observes and reports about the system as an external process. The Probe may
report system information according to a set period, upon system state changes,
or by explicit request from Rainbow.
Each Probe observes a four-stage lifecycle:
* Created - IProbe.create()
* Activated - IProbe.activate()
* Deactivated - IProbe.deactivate()
* Destroyed - IProbe.destroy()
Once created, a Probe may be activated and deactivated numerous times.
Once destroyed, though, a new instance must be created. All probing activities
should occur after the Probe has been activated, in a method like Runnable.run()
as exemplified by the PingRTTProbe class. In the current implementation, where
Probes are coupled with Gauges, a Probe hands each line of output to its Gauge
by calling (IProbe)super.enqueueData(String).
Because a Probe is deployed with the target system, oftentimes it cannot be
invoked by the RainbowDelegate directly, and would thus have to interact with
Rainbow via socket through the Rainbow Service Port (9210). The Perl-based
Probes in the target "znews1-d" exemplifies this usage, for example,
targets/znews1-d/system/probes/diskIOProbe.pl . Socket interaction is provided
by functions in the Rainbow::Probe Perl module. In essence, the Probe-report
protocol via the Rainbow Service Port occurs as follows: init socket ->
register probe -> announce reports* -> (from Rainbow-side) kill probe ->
deregister probe. The traffic across the socket, after the initial connection,
would look something as follows (replace {} with actual values):
Connect to socket /localhost:9210...
CMD relay
$$+{probe.alias}> {probe.name}@{deployment.location}
$$*{probe.alias}> {report.text}
[...]
.KILL. (from Rainbow-side)
$$-{probe.alias}>
Gauges:
A Gauge takes the line-by-line output of a Probe that it is mapped to, which
is assumed to conform to some output format, and interprets the Probe data.
Hence, each Gauge defines a set of one of more output patterns to match (added
via ProbeCoupledGauge.addPattern()), from which it extracts values and processes
those values (with each invocation of the usually overridden lifecycle method
AbstractGauge.runAction() ) in a domain-specific fashion (e.g., calculation of
round-trip network latency).
Gauges report values that update corresponding architectural properties,
the mapping of which is defined in the Gauge Specification file (gauges.yml),
and should also be properly reflected in the SomeGauge.valueNames String array.
Effectors:
An Effector is invoked by Rainbow Adaptation Manager at self-adaptation time
via the method IEffector.execute(java.lang.String[]) . The meanings of the
execute parameters depend on the provision of each effecting operators, and
should be specified accordingly in the Effector Description file (effectors.yml).
Tactic operators should use an Effector according to its description.
-- Configuration of target "contrib0" --
contrib0/
- model/ - folder containing the architecture model files
* contribSys.acme - the architecture model style and system description
* contribSys.mtd - the model visual and other metadata
* gauges.yml - description of the Gauge types and instances to be deployed
* op.map - description to map architectural operators to Effectors
- stitch/ - folder containing the self-adaptation scripts
* contribStrategies.s - the script of adaptation strategies
* contribTactics.s - the script of adaptation tactics
- system/ - folder containing system-specific files
* effectors.yml - description of all the available Effectors provided by or
implemented for the target system
* probes.yml - description of the available Probes in/for the target system
* effectors/ - Perl-based or script-based effectors may appear here
* probes/ - Perl-based or script-based probes may appear here
- utilities.yml - description of the utility dimensions, values, weights, and
tactic attribute vectors
- rainbow.properties - master rainbow configuration properties
- rainbow.properties-<host> - host-specific rainbow configuration properties
Self-adaptation scripts may be edited with the Rainbow Stitch editor, available
as an Eclipse plug-in from the Rainbow Toolkit update site:
http://waterfall.able.cs.cmu.edu/rainbow/update
Please download and install the latest version, and it'll provide basic syntax
highlighting and parse-error support for the Strategy and Tactic scripts.
== Directory Structure ==
- src/ - contribution source directory
* org.sa.rainbow.translator.contrib.effectors/ - custom code for
target-system effectors, which are intended to effect changes in the
system, but may perform other functions, like notification.
* org.sa.rainbow.translator.contrib.gauges/ - custom code for target-system
gauges, which listen to probe-published info and interpret and aggregate
to update the architectural model.
* org.sa.rainbow.translator.contrib.probes/ - custom code for target-system
probes, which should run as part of (or as watcher of) the target system.
- build/ - the Ant build result folder
- drops/ - the Rainbow Master and Rainbow Delegate JAR files, used in deployment
- lib/ - Java libraries, including the source+binary JAR for this SDK, all other
library files are used in deployment
* sdk.rainbow.delegate_<version>.jar - contains the binary as well as source,
so one can easily browse the source, read Eclipse-Javadocs, etc.
* sdk.rainbow.master_<version>.jar - if you have this one, then it contains
Rainbow arch-layer source as well as sdk.rainbow.delegate contents
(in other words, it's a superset of the delegate jar)
* rainbow.common.jar - Rainbow common API that should be deployed with any
probes that are added to the target system
* raindrop.jar - the Jar for the RainDropD daemon that would be included by
the build script with the master and delegate ZIP archives
- targets/ - configuration files for case study scenario instantiations
* znews1-d/ - a fairly complete example set of config files from my own case study
* contrib0/ - the configuration files to compose for the target Rainbow instantiation
- build.xml - the SDK Ant build script
- config.ini - init file to define the target for Rainbow to run, used in deployment
- README.txt - this file here
- version.properties - the version number of the SDK, used by the Ant build script
Structure overview of the SDK JAR:
org.sa.rainbow - Rainbow constants and the RainDrop daemon class
.adaptation - currently contains only an interface for generic arch operators
.core - the main Rainbow service class, RainbowRunnable and core interfaces,
and the RainobwServiceManager to manage the Rainbow Service Port
.core.error - Rainbow exceptions are defined here
.event - Rainbow event infrastructure management classes and interfaces (the IEventService)
.event.jms - JMS-based IEventService implementation
.event.queue - Single-process Queue-based IEventService implementation
.event.rmi - RMI-based IEventService implementation, the primary Rainbow event
service, implemented on top of Queue-based IEventService
.health - Rainbow Health protocol, interface, and handler
.model - description classes for Rainbow model management
.monitor - interface for "delegate" objects of the TargetSystem
.service - IServiceRegistrant implementations for the RainbowServiceManager
.translator - the RainbowDelegate class and common translator interfaces
.translator.effectors - Rainbow Effector protocol, handler, and implementations
.translator.gauges - Rainbow Gauge protocol, interface, handler, and implementations
.translator.gauges.manager - Rainbow GaugeManager generic implementation
.translator.probes - Rainbow Probe protocol, interface, handler, and implementations
.translator.probes.relay - Rainbow Probe relay strategies, currently file-based
and socket-based, with sockets being the primary mechanism
.util - Rainbow utility data structure and commonly used functions
== Build Instructions ==
The Ant build script provided with this SDK offers a number of build targets.
The two important ones are "deploy.lib" and "deploy.all" .
To run the build, right-click on "build.xml" and choose "Run As" -> "Ant Build..."
If doing this for the first time, choose "Hide internal targets...", but don't
sort the targets. Choose "deploy.lib" to build just the Translator contribution
library, or choose "deploy.all" to build the Rainbow Master and Rainbow Delegate
ZIP archives in addition to the contrib.jar.
- deploy.lib - produces "build/lib/lib.translator.contrib.jar".
- deploy.all - invokes deploy.lib, deploy.master.zip, and deploy.delegate.zip .
- deploy.master.zip - produces "build/app.rainbow.master.zip", which could be
deployed on the host where the Rainbow Master would run.
- deploy.delegate.zip - produces "build/app.rainbow.delegate.zip", which could be
deployed on the host where the Rainbow Delegate would run.
- deploy.standalone.contrib.zip - produces "build/standalone.contrib.zip",
which contains the standalone probes that would/should be deployed with the
target system.
== Deployment and Invocation Instructions ==
An instance of Rainbow component should be deployed on each host machine in the
managed target system. One machine is designated the "Master" while the other
machines are designated the "Delegates."
In the initial deployment, unzip "app.rainbow.master.zip" on the Master machine,
and unzip the "app.rainbow.delegate.zip" on the Delegate machines. Make sure
that at least Java 5.0 is available on those machines. Start the RainDrop
Daemon with the following command:
$> java -jar raindrop.jar
Once running, the Rainbow instances can be controlled from the Master host,
either using the Rainbow Oracle GUI, or a remote-control console that would
become available in the future. If changes to the code is necessary, the
software update can also be done remotely using the push-based "Software Update"
service function on each Rainbow instance. In particular, software update may
be performed using a new app.rainbow.master|slave.zip archive, just a JAR
library that needs to be changed, or a ZIP archive containing the set of
files to be changed. Ensure that any partial files conform to the deployment
structure since the Update function assumes that structure.
<rainbow.deployment.dir>/
- drops/ - holds the app.rainbow.master|delegate_<version>.<timestamp>.jar
binary for the Rainbow component.
- lib/ - holds the JAR library on which Rainbow depends, including the
translator contrib JAR.
- targets/ - holds the Rainbow target configuration files.