Last commit for Worklets.html: 946b7c3731aa67c884b95d1794a6dbd88a038d34

removed a faulty </font>

dp2041 [2002-10-28 15:14:56]
removed a faulty </font>
  1. <title>Worklets Documentation</title>
  2. </head>
  3.  
  4. <font color='#000080' size=2 face='Verdana, Arial, Helvetica'>
  5.  
  6. <!-- Header of page -->
  7. <font color='#000080' size=4 face='Verdana, Arial, Helvetica'>
  8. <h4>
  9. Programming Systems Laboratory<br>
  10. Worklets Documentation
  11. </h4>
  12. </font>
  13. <!-- End Header of page -->
  14. <br>
  15.  
  16. <h3>Description</h3>
  17. The Worklets system provides micro-workflow through mobile agents that
  18. adapt computation to component context. It is designed as a mobile
  19. code infrastructure intended for dynamic re-configuration of
  20. third-party systems. Instead of bringing down entire components of a
  21. distributed system at runtime for recompilation, Worklets carrying
  22. Java mobile code can be injected transparently into system components
  23. for incremental adaptation. Host components must include, or be
  24. wrapped with, a generic Worklet Virtual Machine (WVM) and
  25. host-specific adapters exposing indigenous reconfiguration
  26. capabilities. The Worklets System depends on Java 1.4.
  27.  
  28. <p>
  29. The system is principally composed of WVM's, Worklets and
  30. WorkletJunctions. The WVM provides the execution environment as well
  31. as harboring the interface to the system. A Worklet is composed of
  32. WorkletJunctions which contain the execution code and addressing
  33. information for the Worklet. The Worklet thus acts as an agent
  34. bringing the WorkletJunction to the WVM to perform actions which are
  35. specified in the WorkletJunction.
  36. </p>
  37.  
  38. <p>
  39. The typical use of Worklets is to insert WorkletJunctions into a
  40. Worklet and send it into a system running a WVM to monitor the system
  41. by probing or to effect it by modifying system components. A
  42. JunctionPlanner can also be added to WorkletJunctions to specify
  43. meta-data such as the number of iterations to execute. Examples of
  44. these Worklets are included in the distribution and a walk through of
  45. a simple system is provided at the <a target=#walkthrough>end</a> of
  46. the documentation.
  47. </p>
  48.  
  49. <h3>Usage</h3>
  50.  
  51. For Worklets to act on a target system the WVM must be "installed"
  52. into the system. The WVM provides the execution environment in which
  53. the Worklets operate. To install the WVM you need to create a WVM and
  54. pass it a reference to the system to be instrumented: <br>
  55.  
  56. <p>
  57. <font size=2 face='Terminal, Arial'>
  58. WVM _wvm = new WVM(this);
  59. </font>
  60. </p>
  61.  
  62. <p>
  63. This constructor defaults many values which can be specified through
  64. other constructors (please see the <a href=./index.html>Worklets'
  65. Javadocs</a>). In the code above, <font size=2 face='Terminal,
  66. Arial'>this</font> is a reference to the system. The Worklets system
  67. uses this reference to invoke methods provided through a host adaptor
  68. interface (please see the <a href=#examples>examples<a> section
  69. below).
  70. </p>
  71.  
  72. <p>
  73. After the WVM has been installed, Worklets can be sent in to do a
  74. variety of tasks such as invoking interface methods or executing other
  75. bits of code. Since the Workets are transported between WVMs, a
  76. Worklet must be bootstrapped into the Worklets system by an
  77. originating WVM. This can be done by creating a WVM on the
  78. originating system and installing and deploying the Worklet from that
  79. WVM.
  80. </p>
  81.  
  82. <font size=2 face='Terminal, Arial'>
  83. WVM wvm = new WVM(new Object(), InetAddress.getLocalHost().getHostAddress(), "newWVM");<br>
  84. Worklet wkl = new Worklet(null); // create a Worklet<br>
  85. wkl.deployWorklet(wvm); // send it away!<br>
  86. </font>
  87.  
  88. <p>
  89. Worklets themselves are composed of WorkletJunctions which contain the
  90. execution points. Each WorkletJunction has an execute method that is
  91. invoked when the Worklet reaches the destination specified in the
  92. WorkletJunction. Thus one Worklet can act on several systems,
  93. provided the WVM is installed. Also, the Worklet can be communicated
  94. (between WVMs) through different methods, namely sockets or Java RMI.
  95. Additionally, there are ways to secure Worklet transportation, as
  96. described in the <a href="security.html">security</a> section.
  97. </p>
  98.  
  99. <p>
  100. Here is a basic Worklet construction with one WorkletJunction that is
  101. bootstraped with a WVM: <br>
  102.  
  103. <font size=2 face='Terminal, Arial'>
  104. <br>
  105. import psl.worklets.*;<br>
  106. <br>
  107. public class DispatchWorklet implements Serializable {<br>
  108. // create an originating WVM<br>
  109. WVM wvm = new WVM(new Object(), "localhost", "DispatchWorklet");<br>
  110. <br>
  111. WorkletJunction originJunction = null; <br>
  112. WorkletJunction wj = new WorkletJunction("localhost", "target") {<br>
  113. public void init(Object _system, WVM _wvm) {<br>
  114. }<br>
  115. <br>
  116. public void execute() {<br>
  117. System.out.println("Hello System");<br>
  118. }<br>
  119. };<br>
  120. <br>
  121. Worklet wkl = new Worklet(originJunction);<br>
  122. wkl.addJunction(wj);<br>
  123. wkl.deployWorklet(wvm);<br>
  124. System.exit(0);<br>
  125. }
  126. </font>
  127. <p>
  128.  
  129. <p>
  130. The code above creates a WorkletJunction to be sent to a local system
  131. under the name of "target". Once it gets there, the WorkletJunction
  132. will simply print out "Hello System". The <font size=2
  133. face='Terminal, Arial'> originJunction</font> used above specifies
  134. where the Worklet is to return to when finished with all of its
  135. WorkletJunctions. If <font size=2 face='Terminal, Arial'>null</font>
  136. is specified, as above, then it doesn't have to return. <br>
  137. <br>
  138. As the range of Worklet applications vary widely, we provide an <a
  139. href=#examples>example<a> of Worklets being used to probe a system and
  140. then again to effect it. Also, please see the <a href=./index.html>
  141. Worklets' Javadocs</a> for API information.
  142. </p>
  143.  
  144. <p>
  145. <h3><a name="examples">Examples</a></h3>
  146. In this example a simple system is created, instrumented, probed, and effected.
  147. </p>
  148.  
  149. <h4>Example system: Greeter</h4>
  150.  
  151. The example shown here is a simple system where two entities
  152. communicate continuously through a given protocol.
  153. <a href=examples/Greeter.java>Greeter.java</a> provides the interface for
  154. all Greeters and <a href=examples/politeGreeter.java>politeGreeter.java</a>
  155. implements the Greeter. The polite Greeters simply exchange greetings back and
  156. forth while being prompted by a preset greeting. To start the Greeter system,
  157. compile the politeGreeter.java and run, on one terminal: <br>
  158.  
  159. <font size=2 face='Terminal, Arial'>
  160. java politeGreeter localhost 9200 wvm1 localhost 9221 true<br>
  161. </font>
  162. <br>
  163.  
  164. and on another terminal run: <br>
  165. <font size=2 face='Terminal, Arial'>
  166. java politeGreeter localhost 9201 wvm2 localhost 9220 true<br>
  167. </font>
  168.  
  169. <p>
  170. The first and second arguments are the local hostname and socket
  171. number to try binding to. The third argument is the WVM name. The
  172. fourth and fifth arguments are the remote host and port number to
  173. communicate with. The last (sixth) argument is whether to initially
  174. allow communciation and whether to try to initiate a conversation.
  175. When the first invocation above is executed, the other Greeter is not
  176. created yet, so nothing happens. When the second Greeter is created
  177. it starts the conversation with the first Greeter.
  178. </p>
  179.  
  180. <p>
  181. We "instrument" the system, or install the WVM, on the line: <br>
  182. <font size=2 face='Terminal,Arial'> WVM wvm = new WVM(this);<br> </font>
  183. by creating a WVM from within the politeGreeter and passing it a
  184. reference to the parent system. By doing this, Worklets can interact
  185. with the system through the API (Greeter.java).
  186. </p>
  187.  
  188.  
  189. <h4>Probing the Greeter</h4>
  190.  
  191. <p>
  192. Now we want to probe the system to see what's going on inside. For
  193. DASADA related probing, it is important to conform to the
  194. <a href=psl/probelets/Probeable.html>Probelet API</a>. In the following
  195. example I do not implement this API, but in the <a href=#FAQ>FAQ</a> section
  196. I discuss the API as related to Worklets.
  197. <p>
  198.  
  199. <p>
  200. The probe <a href=examples/probeGreeter.java>probeGreeter.java</a> is
  201. sent into the politeGreeter system to find out the greeting being used
  202. and whether they are currently talking. Look at the Probelet class to
  203. see the interaction with the host system. <br> (ie. the line: <font
  204. size=2 face='Terminal, Arial'> String greeting =
  205. ((Greeter)_system).getGreeting(); </font>)
  206. </p>
  207.  
  208. <p>
  209. To execute probeGreeter, run: <br>
  210. <br>
  211. <font size=2 face='Terminal, Arial'>
  212. java probeGreeter localhost wvm1 9200</font>)
  213. </p>
  214.  
  215. <h4>Effecting the Greeter</h4>
  216.  
  217. <p>
  218. Now let's suppose the politeGreeter system wasn't working so great and that
  219. they weren't talking.
  220. </p>
  221. run, on one terminal: <br>
  222.  
  223. <font size=2 face='Terminal, Arial'>
  224. java politeGreeter localhost 9200 wvm1 localhost 9221 false<br>
  225. </font>
  226. <br>
  227.  
  228. and on another terminal run: <br>
  229. <font size=2 face='Terminal, Arial'>
  230. java politeGreeter localhost 9201 wvm2 localhost 9220 false<br>
  231. </font>
  232.  
  233. <p>
  234. Now we'll send in an effector to remedy the system so that the
  235. Greeters are again talking to each other. We do this in <a
  236. href=examples/effectGreeter.java>effectGreeter.java</a>. In
  237. effectGreeter, we invoked the neccessary methods for the Greeters to
  238. talk to each other.
  239. </p>
  240.  
  241. <p>
  242. To execute effectGreeter, run: <br>
  243. <br>
  244. <font size=2 face='Terminal, Arial'>
  245. java effectGreeter</font>
  246. </p>
  247.  
  248. <p>
  249. In effectGreeter we hardcode in the destinations of the
  250. WorkletJunctions simply for convenience. Notice that the probeGreeter
  251. and effectGreeter files are very much the same. The only difference
  252. is in the methods invoked and, of course, the names of the classes
  253. (ie. Probelet vs. Effectlet).
  254. </p>
  255.  
  256. <h4>Example Summary</h4>
  257.  
  258. <p>
  259. In this example we showed a system being installed with the WVM. We
  260. then showed the system being probed and effected. Though this was a
  261. very simple example, it can be used to do further testing and learning
  262. of how Worklets can be used. For example we can actually change the
  263. "protocol", or language, that the Greeters are using. Also, we
  264. restricted ourselves to only invoking API methods but any execution
  265. code can be specified in the execute method (as allowed through
  266. security policy.) Applications can be sent in for execution as well.
  267. These examples are included in the <a href="">Worklets
  268. distribution</a>.
  269. </p>
  270.  
  271. <h3><a name="FAQ">Frequently Asked Questions (FAQ)</a></h3>
  272.  
  273. <ul>
  274.  
  275. <li><p>How can Worklets be used as DASADA probes?</p>
  276.  
  277. <p>
  278. To confrom to the <a href=psl/probelets/Probeable.html>DASADA RTI</a>,
  279. the following methods must be provided:<br>
  280. <table border=0 cellpadding='5'>
  281.  
  282. <tr><td><font color='#000080' size=2 face='Verdana, Arial,
  283. Helvetica'>activate()</font></td> <td><font color='#000080' size=2
  284. face='Verdana, Arial, Helvetica'> Worklets are automatically
  285. active upon reception at WVM. If it is inactive then the methods
  286. provided through the WorkletJunction and JunctionPlanner enable a
  287. user to activate the Worklet (WorkletJunction.) </font></td></tr>
  288.  
  289. <tr><td><font color='#000080' size=2 face='Verdana, Arial,
  290. Helvetica'>deactivate()</font></td> <td><font color='#000080'
  291. size=2 face='Verdana, Arial, Helvetica'> If the Worklet's
  292. WorkletJunctions have associated JunctionPlanners then they can be
  293. suspended using the provided methods. </font></td></tr>
  294.  
  295. <tr><td><font color='#000080' size=2 face='Verdana, Arial,
  296. Helvetica'>deploy()</font></td> <td><font color='#000080' size=2
  297. face='Verdana, Arial, Helvetica'> Worklets provide a deploy()
  298. method. </font></td></tr>
  299.  
  300. <tr><td><font color='#000080' size=2 face='Verdana, Arial,
  301. Helvetica'>undeploy()</font></td> <td><font color='#000080' size=2
  302. face='Verdana, Arial, Helvetica'>The Worklet's WorkletJunctions
  303. can be cancelled using the provided methods.</font></td></tr>
  304.  
  305. <tr><td><font color='#000080' size=2 face='Verdana, Arial,
  306. Helvetica'>install()</font></td> <td><font color='#000080' size=2
  307. face='Verdana, Arial, Helvetica'>Worklets are automatically
  308. installed into the WVM upon deployment and
  309. transport.</font></td></tr>
  310.  
  311. <tr><td><font color='#000080' size=2 face='Verdana, Arial,
  312. Helvetica'>uninstall()</font></td> <td><font color='#000080'
  313. size=2 face='Verdana, Arial, Helvetica'> Worklets can be
  314. uninstalled by cancelling the current and remaining
  315. WorkletJunctions. A lookup function is provided through the local
  316. WVM to find all the currently installed
  317. WorketJunctions.</font></td></tr>
  318.  
  319. <tr><td><font color='#000080' size=2 face='Verdana, Arial,
  320. Helvetica'>query_sensed()</font></td> <td><font color='#000080' size=2
  321. face='Verdana, Arial, Helvetica'>This functionality must be
  322. implemented explicitly.</font></td></tr>
  323.  
  324. <tr><td><font color='#000080' size=2 face='Verdana, Arial,
  325. Helvetica'>sensed()</font></td> <td><font color='#000080' size=2
  326. face='Verdana, Arial, Helvetica'>This functionality must be
  327. implemented explicitly.</font></td></tr>
  328.  
  329. <tr><td><font color='#000080' size=2 face='Verdana, Arial,
  330. Helvetica'>focus()</font></td> <td><font color='#000080' size=2
  331. face='Verdana, Arial, Helvetica'>This functionality must be
  332. implemented explicitly.</font></td></tr>
  333. </table> </li>
  334.  
  335. <li>What about the Effector API? One has not been developed yet.</a>
  336.  
  337. <li>What about security? See <a href=./security.html>Worklet Security</a>
  338.  
  339. <li>Please email <a href="mailto:dp2041@cs.columbia.edu">me</a>
  340. with further questions.</li>
  341.  
  342. </ul> <!--// End - FAQ //-->
  343. </p>
  344.  
  345. <p>
  346. <h3>Errata</h3>
  347. Please email <a href="mailto:dp2041@cs.columbia.edu">me</a> for bug reports.
  348. </p>
  349.  
  350. <h3>Questions, Contact</h3>
  351. <p>Any questions or comments can be directed to <a href="mailto:dp2041@cs.columbia.edu">Dan Phung</a>.
  352. </p>
  353. </font>
  354. <!--Start Copyright-->
  355. <font color='#000080' size=1 face='Verdana, Arial, Helvetica'>
  356. <hr size='1' width="400"/>
  357. Copyright © 2002: The Trustees of Columbia University in the City of New York. All Rights Reserved<br>
  358. Author: <a href="mailto:dp2041@cs.columbia.edu">Dan Phung<a> <br>
  359. Last Modified 20 October 2002
  360. <!--End Copyright-->
  361.  
  362. </body>
  363. </html>