II: The Infospheres Infrastructure User Guidedmz/resources/ii.pdf · Chapter 1 Introduction 1.1...

II: The Infospheres InfrastructureUser Guide1

K. Mani Chandy, Joseph Kiniry, Adam Rifkin, and Daniel ZimmermanComputer Science 256-80

California Institute of TechnologyPasadena, California [email protected]

http://www.infospheres.caltech.edu/

Version 1.0January 23, 1998

1The Infospheres Infrastructure, its specification, implementation, and documentation are Copyrightc© 1996-1998 The California Institute of Technology. All rights are reserved. This work is supported inpart by the Air Force Office of Scientific Research under grant AFOSR F49620-94-1-0244, by the CISE di-rectorate of the National Science Foundation under Problem Solving Environments grant CCR-9527130,by the Center for Research in Parallel Computing under grant NSF CCR-9120008, and by Parasoft andNovell. For more Infospheres information, please see http://www.infospheres.caltech.edu/ on theWeb.

Contents

1 Introduction 11.1 Welcome! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.3 What You Need to Use the II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.4 What Has Changed Recently . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.4.1 Changes In 1.0 Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4.2 Changes In 1.0fc Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.4.3 Changes In 1.0b3 Release . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.4.4 Changes In 1.0b2 Release . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.5 Where is the II Heading? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.6 Installing the Infospheres Infrastructure . . . . . . . . . . . . . . . . . . . . . . . . 81.7 Known Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.8 How to Read This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.9 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2 Infospheres Infrastructure Concepts 152.1 II: A Distributed Object System Framework . . . . . . . . . . . . . . . . . . . . . 152.2 An Introduction to Distributed Systems . . . . . . . . . . . . . . . . . . . . . . . 15

2.2.1 Defining Distributed Systems and Frameworks . . . . . . . . . . . . . . . . 162.2.2 Distributed Systems: Applications . . . . . . . . . . . . . . . . . . . . . . . 16

2.3 Modern Distributed Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.3.1 Distributed System Models . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.3.2 Our Experimental Framework . . . . . . . . . . . . . . . . . . . . . . . . . 17

2.4 Our Vision: A Worldwide Object Network . . . . . . . . . . . . . . . . . . . . . . 182.5 Distributed Objects and Virtual Networks . . . . . . . . . . . . . . . . . . . . . . 19

2.5.1 Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.5.2 Distributed Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.5.3 Virtual Networks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

2.6 Infospheres Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.6.1 Djinns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.6.2 Djinn Communication Layer . . . . . . . . . . . . . . . . . . . . . . . . . . 222.6.3 Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

i

ii CONTENTS

2.6.4 Djinn Masters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.6.5 Infospheres . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.6.6 Fundamental Problems in Distributed Objects . . . . . . . . . . . . . . . . 24

2.7 Where to Go Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

3 Communication using info.net 253.1 A Brief Overview of the info.net Package . . . . . . . . . . . . . . . . . . . . . . 253.2 Using the info.net Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

3.2.1 Hello, World - the Sender . . . . . . . . . . . . . . . . . . . . . . . . . . 303.2.2 Hello, World - the Receiver . . . . . . . . . . . . . . . . . . . . . . . . . . 313.2.3 Hello, World - Revisited . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

3.3 A More Detailed Look at info.net . . . . . . . . . . . . . . . . . . . . . . . . . . 343.3.1 Mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343.3.2 Inboxes to Handle Receiving Messages . . . . . . . . . . . . . . . . . . . . 353.3.3 Outboxes to Handle Sending Messages . . . . . . . . . . . . . . . . . . . . 363.3.4 The MailDaemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373.3.5 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383.3.6 Message Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403.3.7 Remote Class Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403.3.8 Class Loading Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

3.4 Examples Illustrating the info.net Package . . . . . . . . . . . . . . . . . . . . . 413.4.1 Simple Send and Receive with Filtering . . . . . . . . . . . . . . . . . . . . 413.4.2 Waiting for Delivery on One of Several Inboxes . . . . . . . . . . . . . . . 423.4.3 Spamming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423.4.4 Waiting for Delivery on Multiple Inboxes . . . . . . . . . . . . . . . . . . . 423.4.5 A Ring of Message Passers . . . . . . . . . . . . . . . . . . . . . . . . . . . 433.4.6 Synchronized Send and Receive . . . . . . . . . . . . . . . . . . . . . . . . 433.4.7 Places as Messages and Broadcast Mailboxes . . . . . . . . . . . . . . . . . 433.4.8 ReceiveSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

3.5 Caveats and Suggestions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443.5.1 Warnings About the Current info.net . . . . . . . . . . . . . . . . . . . . 443.5.2 Tips for Developers Using info.net . . . . . . . . . . . . . . . . . . . . . 46

4 Creating Djinns 474.1 Using the info.djinn Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

4.1.1 Your Djinn’s Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474.2 Naming Djinns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484.3 Djinn Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

4.3.1 Outbox Association Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . 504.4 Djinn Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514.5 Adding Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514.6 Your Lamp, Your Friend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

CONTENTS iii

4.7 Summoning and Dispelling Djinns . . . . . . . . . . . . . . . . . . . . . . . . . . . 524.7.1 Your Lamp Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524.7.2 The lamp.summon Method . . . . . . . . . . . . . . . . . . . . . . . . . . . 524.7.3 The lamp.dispell Method . . . . . . . . . . . . . . . . . . . . . . . . . . 53

4.8 On Being Dispelled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544.8.1 Your dispell Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

4.9 Djinn Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554.9.1 The lamp.service Method . . . . . . . . . . . . . . . . . . . . . . . . . . 554.9.2 Your service Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

4.10 Other Methods of Importance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564.10.1 The main Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564.10.2 The run Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

4.11 Djinn Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574.12 Djinn Command-line Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

5 The Djinn Master 595.1 What is a Djinn Master? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595.2 Configuring Your Djinn Master . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

5.2.1 The master.res File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605.2.2 The dmrc File - General Discussion . . . . . . . . . . . . . . . . . . . . . . 615.2.3 The dmrc File - Specifics . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

5.3 Djinn Master Mode Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635.4 Some Example dmrc Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

5.4.1 Hello World . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635.4.2 Webster Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645.4.3 Mutual Exclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655.4.4 Persistent File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

5.5 Invoking Operations via the Djinn Master . . . . . . . . . . . . . . . . . . . . . . 655.5.1 Summoning Djinns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665.5.2 Dispelling Djinns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665.5.3 Requesting Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

5.6 Invoking Operations on the Djinn Master . . . . . . . . . . . . . . . . . . . . . . . 665.6.1 Summoning a Djinn Master . . . . . . . . . . . . . . . . . . . . . . . . . . 675.6.2 Dispelling a Djinn Master . . . . . . . . . . . . . . . . . . . . . . . . . . . 675.6.3 Requesting Services from a Djinn Master . . . . . . . . . . . . . . . . . . . 67

5.7 The Output Generated by the Djinn Master . . . . . . . . . . . . . . . . . . . . . 675.7.1 Use of the info.util.Debug Class . . . . . . . . . . . . . . . . . . . . . . 67

6 Example Djinns 696.1 Summoner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706.2 HelloWorld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726.3 Recursive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

iv CONTENTS

6.4 Calendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766.5 Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766.6 Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786.7 Persistent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796.8 OutboxAssoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806.9 Middle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806.10 TokenPasser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 816.11 Test Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826.12 Applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826.13 DispellButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

A Debugging II Djinns 83A.1 Debugging Output in the II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83A.2 Submitting Bug Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83A.3 Known Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

B Glossary 85

Chapter 1

Introduction

1.1 Welcome!

Welcome! This is the README and User Guide introduction for the Infospheres Infrastructure,release 1.0. This final release has been through six release levels (alpha0, alpha1, beta1, beta2,beta3, fc) so we believe that it is pretty solid now.

The Caltech Infospheres Infrastructure (II) is a distributed system framework that provides:

• A generic object model.

• A variety of messaging models, including asynchronous, synchronous, and remote proce-dure/method calls.

• A variety of distributed system services, including local and global naming, object instancecontrol, object persistence, and dynamic object extensibility.

Using the II tools, a developer can build robust distributed systems on the Internet. Theideas, algorithms, and theories developed within the II framework are directly applicable toexisting distributed systems and frameworks. As implemented, the framework is written in Java,allowing cross-platform development.

1.2 Supported Platforms

This final release of the II supports JDK 1.1 only. If you really need to run the II on a 1.0.XJDK, drop us a line and we’ll provide a package for you. The change is really only the removalof a few references to the Serializable interface. So, if you have a 1.0.X Java RMI installed,you should be fine.

This release has been successfully tested on the following Java ports as of 20 December 1997:

• Asymmetrix’s Super-Cede 1.0 on Windows NT 4.0

• JavaSoft JDK 1.0.2 port chapman:10/12/12-23:12 under Linux emulation on NetBSD 1.1B

1

2 CHAPTER 1. INTRODUCTION

• All JavaSoft JDK 1.0 releases on Windows NT 4.0

• All JavaSoft JDK 1.1 releases on Windows NT 4.0

• All JavaSoft JDK 1.0 releases on SPARC Solaris 2.X

• All JavaSoft JDK 1.1 releases on SPARC Solaris 2.X

• All JavaSoft JDK 1.1 releases on Intel Solaris 2.X

• SGI JDK 1.1 on SGI Irix 6.2

• Microsoft Visual J++ 1.1 on Windows NT 4.0

• Symantec Cafe 1.5.X on Windows NT 4.0

• All Apple Macintosh OS Runtime For Java releases on Mac OS 7.X, 8.X

The release is known not to work on the following Java ports as of 21 August 1997:

• JavaSoft JDK 1.0.2 port “chapman:09/05/05-07:40” on Linux

• JavaSoft JDK 1.0.2 port “sbb:05/19/97-22:33” on Linux(on these two platforms, if messages are never sent to nonexistent MailDaemons, the release functions normally)

• Metrowerks Java (CodeWarrior 11) on Mac OS 7.X, 8.X

We would like to test the II 1.0 release on other platforms as well; please let us know if yourun the II on one of the following platforms (which are otherwise untested as of 25 December1997):

• Asymmetrix SuperCede 1.0 on Windows 95

• Digital Equipment Corporation JDK 1.0.2 port to Digital UNIX 4.0

• Hewlett-Packard JDK 1.0.2 on HP-UX 10.10

• IBM JDK 1.0.2 on AIX 3.X (http://www.ibm.com/Java/home.html)

• IBM JDK 1.0.2 on Windows 3.X

• IBM VisualAge for Java on Windows 95/NT

• JavaSoft JDK 1.0.2 port “chapman:10/12/12-23:12” on a Linux 1.38 kernel

• JavaSoft JDK 1.0.2 port “ritao:03/18/18-03:01” on Irix 5.3

• JavaSoft JDK 1.0.2 on Windows 95

• JavaSoft JDK 1.0.2 on Mac OS 7.X, 8.X

• JavaSoft JDK 1.1 on a Linux 1.38 kernel

• JavaSoft JDK 1.1.3 on x86 Solaris 2.X

• Metrowerks Java on BeOS

• Metrowerks Java on Windows 95/NT

• Microsoft Visual J++ 1.1 on Windows 95

1.3. WHAT YOU NEED TO USE THE II 3

• Roaster Technologies’ Roaster Professional DR2.3 on Mac OS 7.X, 8.X

• Sun’s Java Workshop on Solaris 2.X

• Sun’s Java Workshop on Windows 95

• Sun’s Java Workshop on Windows NT

• Symantec Cafe 1.5.X on Mac OS 7.X, 8.X

• Symantec Cafe 1.5.X on Windows 95

1.3 What You Need to Use the II

To use the II packages, you need a Java Developer’s Kit. Sun Microsystems provides the JDKfree of charge for SPARC Solaris, x86 Solaris, Windows NT and Windows 95. Apple Computerprovides the Mac OS Runtime for Java Software Development Kit free of charge for Mac OS7.X and 8.X. Other ports, such as the ones mentioned in our lists of tested and untested Javaplatforms, are available from other sources on the Internet or through software vendors.

The II is being used in the CS 141 - Distributed Computation Laboratory class at Caltech.The class used the package extensively in November, 1996, writing autonomous poker-playingdjinns that competed in a gaming tournament. This test pitted several dozen djinns against eachother, interacting in up to five simultaneous sessions/games. Students’ recommendations helpedus make our packages substantially smaller, faster, more reliable, and more consistent than theprevious releases.

However, this upgrade comes at a cost: the djinn API changed substantially from the alphato the beta release, and the package was restructured so it is easier to use and more portable tonon-UNIX operating systems. Existing djinns that conform to the alpha release port to the newAPI in under a half hour. See section 1.4 for information on what has changed for this releaseand how to port your djinns.

The II has also used to build several other distributed systems:

• Autonomous poker playing objects, as mentioned previously.

• A global resource reservation tool that integrates a Tk/Tcl front-end with a Java/II backend to provide the user with an interactive interface for reserving slots on geographicallydistributed supercomputers with individual resource reservation schemes. See our ISCOPE’97 paper available from our web site for more information.

• A research framework for developing client-server systems. The JEDI system lets a devel-oper build client-server systems without having to go through the process of stub/skeletoncompilation. See our HICSS ’98 paper for more information.

• A peer-to-peer distributed editor called SimulEdit. This editor lets users join and leave anediting session dynamically and is fully fault tolerant. See our Dr. Dobb’s Journal paperfor more information.


• A distributed artificial life simulator called DALI. This system lets the user construct andistributed asynchronous simulation system that is grounded in notions of simulated alife(genomes specify behavior, speciation, pack behavior, etc.). The system has the potentialto scale extremely well given Infospheres 1.0’s scaling properties (i.e. hundreds of thousandsto millions of interacting agents are possible given just a few nodes in a network). See theDALI group’s web pages, available via our web site, for more information.

• A peer-to-peer autonomous agent auctioning system. This system lets the user specify a setof items that they are interested in purchasing and a set of items that they are interestedin selling. The example application uses compact discs or used books. The user alsospecifies how much they are willing to pay for/get for the items and what sort of strategiesto employ in buying or selling the items (first hit, highest bid after a time window, etc.)The system then autonomously posts the selling information to a variety of communicationvenues (organized NetNews groups, web servers, and multicast addresses are in the currentdesign) and spawns agents to autonomously search through these same sources for itemsof interest. Once a possible match is found, bartering agents then attempt to make thepurchase/sale according to the user’s preferences.

As you can see, several interesting dynamic distributed systems have been built with theII. We have found it to be a very useful tool in the instruction and construction of distributedsystems and algorithms.

1.4 What Has Changed Recently

1.4.1 Changes In 1.0 Release

Only one API change took place in this, the final release of II 1.0. This change was necessitatedby Java’s inability to resolve method naming conflicts across packages. Specifically, since wewished to provide a base class for applet djinns, we needed the class DjinnApplet to inheritfrom java.applet.Applet. But, Applet inherits (eventually) from java.awt.Component, whichalready has a getName() method. Thus, the dilemma.

The change is as follows:

• The method info.Djinn.getName() was renamed to info.Djinn.getDjinnName().

Only two bugs were reported in the 1.0fc release, both of which have been fixed:

1. A NullPointerException was being thrown at startup if the package had not yet beeninstalled. This was correct behavior, but the Djinn Master should have then shut downcleanly, which it did not.

2. The Instance Location pull-down menu on the Summoner was not saving the correct entriesthat were typed in the corresponding field.

1.4. WHAT HAS CHANGED RECENTLY 5

Additionally, support for the process flag has been turned on in this final release of the II.The code actually always existed, but only recently have JDKs worked correctly with respect toexecing new processes. This means that one can instantiate new distributed objects in their ownaddress spaces as opposed to in their own thread groups. See chapter 5.3 for more information.

Other improvements include:

1. Integration with the Java Beans framework.

2. Base Djinn classes: DjinnBean, DjinnApplet, and DjinnServlet.

3. Works with Java RMI, Serialization, and Java IDL.

4. A suite of distributed systems have been developed with the II.

Development on several components in support of the PSEWare Project is underway. Thesecomponents will demonstrate the ability to compose distributed Djinns as beans interactivelyvia a bean composition tools like Java Studio. These components will be released as a separatepackage in 1Q98.

1.4.2 Changes In 1.0fc Release

Version 1.0fc of the II is expected to become the final 1.0 release. Several changes have beenmade between releases 1.0b3 and 1.0fc, including both feature additions and bug fixes. Thefollowing features have been added in the 1.0fc release:

• Instance djinns can now be resummoned from persistent storage, by filling in the summoningDatefield of the DjinnName during summoning. If an attempt is made in this way to summonan instance djinn which doesn’t exist in persistent storage, an exception is raised in thesummoner.

• A new command line switch, -iid, has been added. This specifies the summoning date ofthe djinn, in the form of a long integer (as obtained from java.util.date.getTime()).

• The getParentName() method of info.djinn.Djinn now returns the DjinnName of thedjinn which summoned the particular djinn thread which calls getParentName().

• A new method, getInitialParentName(), has been added to info.djinn.Djinn. Itreturns the DjinnName of the djinn’s initial parent (ie: the djinn which caused that djinnto be thawed most recently).

The following functionality issues in 1.0b3 are addressed in the 1.0fc release:

• Calling readObject() on an instance of info.net.Message (or a subclass thereof) whichhad been created locally (ie: not received on an Inbox) would cause a NullPointerExceptionto be thrown. This caused the Calendar example to not restore its persistent state, and


made it impossible to use writeObject() and readObject() to store and retrieve mes-sages in persistent storage. This problem has been fixed - readObject() can now be calledon any instance of info.net.Message.

• The method info.djinn.DjinnName.equals() has been changed such that two DjinnNameswhich differ only in their summoningDate field are not considered to be equal.

• The AWT code, added in 1.0b3, has been modified to be more compatible, and to providea more uniform appearance, across various platforms’ implementations of the JDK.

1.4.3 Changes In 1.0b3 Release

Version 1.0b3 of the II is primarily a maintenance release. The following features have beenadded in the 1.0b3 release:

• A copyright notice appears in an AWT dialog whenever a djinn is started from the commandline. This dialog disappears after approximately 15 seconds or when dismissed by the user.

• A new command line switch, -iinoawt, has been added. This disables the II’s use of theAWT, allowing djinns to be run from the command line on systems that have no graphicdisplay capability.

• A new method, receive(long), has been added to info.net.Inbox. This allows a receiveto be performed with a specified timeout period. If a message is received within the timeoutperiod, it is returned (just as in the non-timeout version of the call); otherwise, null isreturned.

The following functionality issues in 1.0b2 are addressed in the 1.0b3 release:

• In 1.0b2, under certain Java runtime environments, a MailDaemon would not shut downproperly on a destroy() call because of subtleties (i.e. bugs) in certain implementa-tions of java.net.DatagramSocket. A MailDaemon will always shut down properly on adestroy() call in 1.0b3.

• In 1.0b2, when a djinn made use of the AWT in any way, the II was unable to properlydetect the termination of that djinn. This caused many problems with respect to manage-ment of state files and various info.master.DjinnMaster and info.djinn.Lamp internals.In 1.0b3, djinns which make use of the AWT are handled correctly by the II.

• In 1.0b2, summon requests for a running djinn made through that djinn’s master werenever forwarded, regardless of the mode in which the djinn was running. In 1.0b3, requestsare correctly forwarded in the manner dictated by the djinn’s run mode.

• In 1.0b2, requests received by a master for a djinn belonging to a user other than themaster’s owner were handled as though they were requests for a djinn belonging to themaster’s owner. These requests are rejected by the master in 1.0b3.

1.4. WHAT HAS CHANGED RECENTLY 7

1.4.4 Changes In 1.0b2 Release

The packages info.djinn and info.master were completely redesigned between the 1.0b1 and1.0b2 releases. Most changes occurred underneath the II hood, so previous II users need only beconcerned with the changes to the class structure and API. General changes to the II include:

• The tests package has been removed. The package info.net.tests.infonet has beenrenamed to info.demo.net.

• The packages info.app, info.awt, info.io, info.system, and info.tool have beenremoved.

• The classes info.awt.OkDialog and info.awt.YesNoDialog have been moved into the(unreleased) Djinn Initiator. All other info.awt classes have been removed completely(they are used in the unreleased and unported djinn generator).

Changes in the communication layer. The info.net package has been debugged andsomewhat re-engineered. See chapter 3 for full details about the changes, including:

• The classes AllFilter, Debug, ClassFilter, FilterSet, MailDaemonDM,

MessageClassLoader, NumberFilter, and Pingbox have been removed.

• The classes MDException, MessageQ, and Multicastbox have been added.

• The Filter and MultiURLClassLoader classes have been re-engineered.

Changes in djinns and Djinn Masters. The info.djinn and info.master packages havebeen completely re-engineered. See chapter 4 and chapter 5 for full details about the changes,including:

• The dm directory in the previous release is now called ii data. It contains more shellscripts and batch files to support running Djinn Masters and cleaning up state files.

• The state file system is now consistent with a user-per-djinn-master model. The previouspackage provided a model by which multiple users could use the same djinn master. Whilethis mode is not forbidden in the current system, it is not the main intent of the package.

• The djinn master.resource file has been renamed master.res to support file systemarchitectures with path and filename length and extension issues.

• The naming mechanism used in the persistence subsystem has been completely redesignedand rewritten to support file system architectures with path and filename length and ex-tension issues.


• The dot dmrc or .dmrc file from the previous release has been renamed dmrc to supportfile system architectures with path and filename length and extension issues. Also, this fileis now located in your personal ii data directory, not in your home directory.

• The alpha version of the djinn master that was implemented in C has been removed.

Changes in demo examples. The info.demo package has been completely re-engineered.See chapter 6 for full details about the changes, including:

• The example djinns have been moved from the djinns package to the info.demo packageto reflect that they are II demonstration programs and not full-fledged applications ordjinns. The djinns package has been removed completely.

• None of the example djinns depend on shell scripts, executables, or other non-Java appli-cations. They are all 100% pure Java djinns.

• The Forwarding djinn has been removed from the package. It is replaced by the exampleServer djinn found in the info.demo.server package.

• The Mail and News djinns have been removed from the package. They still exist, but havenot yet been ported to the new API.

• Several new demonstration djinns have been added. See the packages info.demo.middle,info.demo.calendar (which was moved from info.app.calendar), info.demo.outboxassoc,info.demo.server, and info.demo.testsuite.

1.5 Where is the II Heading?

Development on II 2.0 is nearly complete. The first release will take place in 1Q98. II 2.0 iscompletely new distributed system, implemented from the ground-up, and has many new andinnovative features not available on any distributed computing platform.

1.6 Installing the Infospheres Infrastructure

Step 1: Unpack. Unpack the tar file using your favorite tools. On Windows 95 or NT, useany unzip package, but that package must support long filenames. On the Macintosh, justdouble-click on the archive (if you don’t have StuffIt Expander, you should download it fromAladdin Systems at http://www.aladdinsys.com/. On a UNIX system, unpacking is usuallyaccomplished with something like:

zcat II-1.0.tar.gz | tar xpvf -

1.6. INSTALLING THE INFOSPHERES INFRASTRUCTURE 9

Step 2: Prelude to Creating Your Personal ii data Directory. The notion of a “homedirectory” in Java is not necessarily identical to that which your operating system provides.Because of this interesting discrepancy, you need to run the “boss” of our system, the DjinnMaster, so that it can tell you where to copy the supplied ii data directory. You do so byrunning the Djinn Master with the batch file or shell script that we provide.

The ii data directory is the place where the Infospheres Infrastructure stores all of its infor-mation. This directory, once installed, should not be moved, renamed, or hand-modified, unlessyou are explicitly told otherwise.

Starting up the Djinn Master is different for the three main flavors of operating systems. Thisis the case only because the bootstrap mechanism is different – the code executed by the scriptsare all the same 100% pure Java. Let’s assume that you have just unpacked the distribution andyou see a directory/folder called info.

• If you are running on a Windows system (95 or NT), execute the batch file called info\ii_data\master.bat.

You can run this script with the Run command on your Start button, from a commandprompt, or by double clicking on the icon for the batch file through Explorer.

• If you are running on a UNIX system, execute the shell script info/ii data/master.sh

from a shell or from the visual interface that your operating system uses (such as CDE).

• If you are running on a Macintosh, use whatever method is provided by your runtime tostart classes. We have included sample settings for JBindery (part of Apple’s Mac OSRuntime for Java Development Kit) for the Djinn Master, and all that is necessary isto load them into JBindery, add the provided zip files to your classpath (or drop theminto the MRJClasses folder within your Extensions folder), save the configuration as anapplication, and run it. Note that JBindery allows you to specify properties, so if youmanually specify “user.home”, you can skip this step entirely.

After starting up the djinn master, you should see something like the following:

sphere:ii_data> ./master.sh

Your Java runtime believes that your home directory is the following:

/ufs/comp/kiniry

Copy the Infosphere Infrastructure’s ‘ii_data’ directory/folder into exactly

that directory. Specifically, you need the ‘master.sh’ or ‘master.bat’

scripts, the ‘master.res’ support file, and the ‘state’ directory/folder

for your Djinn Master to run properly.

From now on, you should run your Djinn Master with the appropriate script

from within your personal ‘ii_data’ directory.

The Djinn Master is at your service...

Exception: DjinnThread.run:

You have not yet installed the package properly since the ii_data

is missing. Please read and follow the installation directions in

the introduction of the Infosphere Infrastructure User’s Guide.

If your Java runtime believes that your home directory is “.” (current directory) then yourruntime is broken, and the djinn master will offer possible solutions.


Step 3: Create Your Personal ii data Directory. Next, as suggested by the Djinn Master,you should create your own personal ii data directory. You only have to do this once ever.Follow the Djinn Master’s instructions and copy the ii data directory from the InfospheresInfrastructure that you recently unpacked to the directory indicated by the Djinn Master.

Following the above example, I would copy the ./info/ii data directory of the package tomy /ufs/comp/kiniry directory with a command like:

cp -R ./info/ii_data /ufs/comp/kiniry

Or, if I were on a Windows or Macintosh box, or I used a File Browser on a UNIX system, Iwould just drag-copy the folder into the specified directory.

Step 4: Set Up the master.res File. The Djinn Master, a kind of a personal mini-ORBthat is part of the Infospheres Infrastructure, needs to have some knowledge of your system.You summarize this information in a file called master.res. The file is found in the ii data

directory that you just copied. You are responsible for modifying it so that the Djinn Mastercan find various tools and data on your system.

Look at the resource file and follow the directions therein so that the package reflects yourhierarchy. Note that, for most folks, the only elements that need be defined in the master.res

file are CLASSPATH and PATH. See chapter 5 of the User Guide for detailed information.Note that the ii data directory is the location from which you will normally run your Djinn

Master from now on. This is where the persistent state of summoned djinns (your personaldistributed objects) is organized and stored across instances.

Step 5: Make a Personal dmrc File. The dmrc is the file which describes your particularInfosphere. It details all of the djinns that are part of your environment. The ii data directorythat you just set up has a default dmrc file for you in it. Please glance at the dmrc file now.When you are sufficiently comfortable with the package (after reading more of this User Guideand playing with some demonstration djinns), you can modify your dmrc to reflect your localinstallation. We will be providing tools in the future for automatic creation and maintenance ofthese support files.

Note that some of the initial dmrc entries point to a Web server here at Caltech. We willattempt to keep that Web server up and running as much as possible so that you can remoteclassload new djinns. You should attempt to set up, or take advantage of, a local Web serveras soon as possible or change the references to Caltech http: URLs to local file: URLs.This is important because (i) you should not be dependent upon Caltech for serving djinnimplementations, (ii) you will wish to classload your own local djinns that you modify or write,and (iii) you do not want to classload Java code over long, unreliable, or slow network links.

Step 6: Set the CLASSPATH. You must make sure that your shell’s default CLASSPATH variableis set such that the II class hierarchy is included. Specifically, the path ./info/source/ (butwith a full path) needs to be a component in your CLASSPATH.

1.7. KNOWN PROBLEMS 11

Note that the II classes are also available via our web server in java archive (jar) and zipformats.

Under UNIX this is done by modifying your shell startup (.cshrc, .bashrc, .login or theequivalent) and including a line that sets CLASSPATH to the appropriate value. Under WindowsNT, Windows 95, and the Macintosh follow the directions provided with your Java package. Allcomponents of the II are package-ized, so this element is the only addition you need to make toyour CLASSPATH.

Step 7: Set Your PATH. You must also make sure that the Java runtime of your Java De-veloper’s Kit is in your shell’s default PATH as well. Meaning, in any given command-line shell,typing “java -help” should run the Java executable properly. On Windows NT, Windows 95,and Macintosh you usually do not have to worry about this since they all use various kinds ofresource registration for automatically running programs.

Building Release Components. We do not ship the source code for the bulk of the package.We do provide source for all the example djinns and test code. We provide compiled versions ofall code. It is likely that you will want or need to re-build the demonstration djinns while youare learning about the II.

We use Gnu’s make utility for our project build management and latex and latex2html forour User Guide. So, if you have a UNIX machine and have Gnu make and latex installed onyour machine then you can just do a “make” at the top-level and everything in the package willbuild.

If you do not have Gnu make, or are on a non-UNIX box, you need to build the environmentin the manner that is appropriate for your platform. This may mean changing directories to everydirectory in the ./info/source/info/demo path and running ‘‘javac *.java’’, or buildinga project with our class hierarchy with your Java IDE.

Removing the Package To un-install the package, you only need remove the unpacked info

tree (created when you performed step one) and your personal ii data directory. The InfospheresGroup is against products which scatter information all over your filesystem - just say no to diskentropy!

1.7 Known Problems

The short-list of our current problems would include:

• The pull-down boxes in the GUI summoner no longer work in JavaSoft’s Windows 1.1version and under Apple’s JRE on the Macintosh. Given that most of our users are onUNIX, and that most of the non-UNIX ports have broken 1.0 AWT functionality in their1.1 ports, we decided it wasn’t in our best interest spending hours working around otherpeople’s bugs. Thus, while the summoner still works fine for its base functionality, this


convenience mechanism is not available. It might very well work under other JDK ports;we didn’t test any others.

• We witnessed several bugs in JavaSoft’s JDK 1.2 beta 3 under Windows. We highly suggestusing a stable version of JDK 1.1 to run this package.

• In the Linux and BSD JDK 1.0.2 ports, Motif scrollbars are not implemented correctly/reliably.

• Thread termination detection is not implemented properly in many JVM implementationson Windows. We do know that Sun’s and Cafe’s JDK 1.0.2 implementations are faultyand that Sun’s JDK 1.1.3 works some of the time. Thus, if you are using Cafe as yourdevelopment environment in Windows, you need to get Sun’s JDK 1.1.3 to run the II.

• In all currently-released versions of the Java Virtual Machine, threads started by the AWTdo not terminate when the AWT is no longer being used, which causes problems in detectingthe termination of djinns which use the AWT. In order to circumvent this implementationproblem, a special threadgroup is created for AWT threads by the Lamp every time adjinn is started from the command line. Unfortunately, under JDK 1.1.3 and earlier underWindows NT, there seems to be a race condition in the AWT which occasionally causes ahard freeze of the VM when this threadgroup is created. The -iinoawt command line flagprevents the Lamp from starting the AWT, and it should be used if freezes are experiencedand when running djinns on systems with no graphics capability (while the II will auto-matically detect when the AWT classes are unavailable, it cannot always detect when adisplay is unavailable because of limitations in certain runtime systems).

Reporting Bugs. The more information we have, the more likely it is we can fix the bug.Please supply all of the following information and mail it to [email protected]. Infuture releases, we plan to provide a form-based bug reporting mechanism. Make sure you provideall the below information with your bug report.

1. Operating System and Version:

2. Java Port and Version:

3. Infospheres Infrastructure Version:

4. Example Code:

5. Exception/Thread Trace:

6. Comments:

7. Contact Information:

1.8. HOW TO READ THIS DOCUMENT 13

1.8 How to Read This Document

Installation. Please follow the directions in section 1.6 to set up the Infospheres Infrastructure.If you have any problems with installation, please email the bug reporting address as discussedin Section 1.7.

Terminology. The object, distributed computing, and Web worlds have become quite con-fusing places with all the overloaded words flying around. We have written a glossary of termsto familiarize you with the requisite jargon; look for our glossary in Appendix B of this UserGuide.

Demonstration Examples. To take the Infospheres Infrastructure for a test drive, follow thedirections in chapter 6, Example Djinns. We are working on providing a means of demonstratingthe Infospheres Infrastructure via the Web. This means that all you will need is a Java-capableWeb browser to try out our distributed system and its demos with point-and-click ease.

Create Your Own Djinn! After reading the documentation (the online APIs and this UserGuide), you are set to write your own djinn. You can accomplish this by using the HelloWorld

example djinn you checked out, or by just creating your own subclass of info.djinn.Djinn anddropping in your own code. Have fun!

1.9 Acknowledgments

The Caltech Infospheres Infrastructure is the combined effort of several people discussing conceptsand design over a few years, led by Professor K. Mani Chandy and Caltech graduate studentsJoseph Kiniry, Adam Rifkin, and Daniel Zimmerman. Many members of the Caltech communityhave contributed to the project, including members of the CS 141 class; undergraduates AnandChelian, Boris Dimitrov, Huy Le, Jacob Mandelson, Luke Weisman, Matt Richardson, andWesley Tanaka; graduate students Berna Massingill, Paul Sivilotti, Eve Schooler; postdoc JohnThornley; and staff member Mack Rhinelander.

Sponsors. The Infospheres project is sponsored by the Air Force Office of Scientific Research(grant AFOSR 91-0070), the CISE directorate of the National Science Foundation under ProblemSolving Environments (grant CCR-9527130), the Center for Research in Parallel Computing(grant NSF CCR-9120008), and the Parasoft and Novell Corporations. This work has also beenpartially supported by a National Science Foundation Graduate Research Fellowship.

Contacting Us. If you have any comments, use [email protected] to email us.


Copyright. The Infospheres Infrastructure (II) — Copyright c© 1996-98 California Instituteof Technology. All Rights Reserved. All material contained within the Infospheres Infrastructurepackage is protected by the copyright laws of the United States and international treaties.

By downloading our software, you agree to the following conditions:

1. You may not redistribute any of this software or documentation without obtaining explicitpermission from the California Institute of Technology.

2. You may not use this software for any commercial purpose without obtaining explicitpermission from the California Institute of Technology.

3. The California Institute of Technology shall not be obliged to provide support for thissoftware.

Chapter 2

Infospheres Infrastructure Concepts

In this chapter, we explore the general principles underlying the design of distributed objectsystems. If you want to dive directly into our packages, simply jump ahead to chapter 3.

2.1 II: A Distributed Object System Framework

The Caltech Infospheres Infrastructure (II) is a distributed system framework that provides:

• a generic object model;

• a variety of messaging models, including asynchronous, synchronous, and remote proce-dure/method calls; and

• a variety of distributed system services, including local and global naming, object instancecontrol, object persistence, and dynamic object extensibility.

Using the II tools, a developer can build robust distributed systems on the Internet. Fur-thermore, we are extending the II both to support interoperability with other distributed systemmodels and to use emerging Java standards. The ideas, algorithms, and theories developedwithin the II framework are directly applicable to existing distributed systems and frameworks.As implemented, the framework is written in Java, allowing cross-platform development.

2.2 An Introduction to Distributed Systems

An understanding of distributed systems is required to use the II at this point in time. Much ofthe system design is geared toward future work that will let non-programmers create powerfulpersonalized distributed programs and systems; however, the II is primarily of interest right nowto distributed system programmers. To bring non-programmers up to speed, we briefly discussdistributed systems here.

15

16 CHAPTER 2. INFOSPHERES INFRASTRUCTURE CONCEPTS

2.2.1 Defining Distributed Systems and Frameworks

A distributed system is a set of cooperating entities that run in logically different memorylocations. In the degenerate case, a single computer can be a distributed system if it can runmultiple processes that communicate using interprocess communication (IPC) mechanisms likesockets. Distributed systems are often prototyped on single-processor machines, which givea programmer a high degree of control over system conditions. However, in the real world,distributed systems often have geographically scattered components.

Frameworks, which aid in distributed system development, are pre-built sets of code, tools,and documentation that help programmers develop reliable systems more easily than fromscratch. The main cost of using frameworks is that they can impose constraints on programmingstyle and structure, and often they are not suited to a particular application the developer hasin mind.

The Open Software Foundation’s Distributed Computing Environment (DCE) is an exampleof a commercial distributed system framework. DCE provides a suite of tools and services tosupport distributed system creation primarily in the C programming language. These servicesinclude a distributed file system, time synchronization, remote procedure calls, naming, andthreads.

2.2.2 Distributed Systems: Applications

Some systems that benefit from a distributed architecture are:

• Electronic Mail (source-initiated information transmission);

• Domain Name Service (hierarchical, cached, client-pull/server-push based naming acrossgeographic regions);

• World Wide Web (semi-structured on-demand information);

• Technical Report Archive (enterprise document management); and

• Automated Bank Tellers (centralized database access, distributed transactions, electroniccommerce).

Some of these applications are available as commercial distributed systems. For example,Lotus Notes is an enterprise-specific distributed application that provides distributed documentstorage, electronic mail, and workflow control. Recent initiatives in the marketplace to theInternet (and to intranets) are rapidly broadening the scope of distributed system applicationssignificantly.

2.3. MODERN DISTRIBUTED SYSTEMS 17

2.3 Modern Distributed Systems

We divide the people who build today’s component-based distributed systems into four sets: thestart-from-scratchers, the custom solution providers, the compositional system builders, and thehybrid system builders.

• The start-from-scratchers are folks who like to implement everything themselves. Thisapproach is suitable for small systems.

• A custom solution provider adapts its own technologies to the problem at hand, allowingit to construct larger systems.

• A compositional system builder modifies components from off-the-shelf toolkits. Theirspecialized solutions often lack portability.

• The hybrid approach allows developers to patch together a solution using the other threemethods where appropriate: building some components from scratch, using some compo-nents from their personal arsenals, and using some off-the-shelf components.

Each method is suitable for different solutions, based on factors such as needed customization,portability, available resources, and desired development time. The II is useful for buildingdistributed systems using the hybrid approach.

2.3.1 Distributed System Models

Distributed systems can be client-server or peer-to-peer. In client-server systems, one or moreclients connect to one or more servers and request data. For example, in the World Wide Web,the servers provide the information in the form of Web pages, and the clients are browsers thatdisplay that information in a meaningful way. The Common Object Request Broker Architecture(CORBA) is also based on client-server: the clients are object programs, and the servers areobject request brokers. By contrast, in peer-to-peer systems, all programs in the system canbehave as both clients and servers, able both to deliver and manipulate data. With the II,developers can create both client-server and peer-to-peer systems.

2.3.2 Our Experimental Framework

Our programming model is: communicating persistent objects accessible over the Internet. Everyobject, whether active or stored, has a unique name. Collections of objects connect together ina virtual network to perform session-length tasks. Objects use messages to communicate witheach other.

Objects in the Infospheres Infrastructure (version 1.0) are called djinns. Djinns:

• are uniquely named;

• can be persistent;


• can be multi-threaded;

• can interoperate with other programs, services, and infrastructures; and

• can find and connect to these other services automatically.

Djinns communicate asynchronously using messages sent between mailboxes. A djinn’s mail-boxes are message queues that are handled and processed by a the djinn’s maildaemon thread.The communication mechanisms in II, including mailboxes and messages, are described in chap-ter 3; djinns are introduced in chapter 4 and illustrated with demos in chapter 6.

2.4 Our Vision: A Worldwide Object Network

Distributed systems in the future could potentially span the globe, subsuming every hardwareand software resource on the Internet. This global distributed system has many names: theInfospheres group calls it a Worldwide Object Network (WON), Resnick and Baker call it SeasOf Gazillion Shadows (SOGS), and Orfali, Harkey, and Edwards call it the Intergalactic ObjectNetwork (ION). The objects participating in the system may be supporting hand-held devices,home appliances, scientific instruments, or software tools. An analogy for such an infrastructureis today’s worldwide telephone network. Note that this is only an analogy; II is in no sensemodeled after the telephone network.

The telephone network is an enormous virtual circuit bus that spans the globe. Its informationflows through any medium, from copper to glass and even air! Technologies are used to insurethat communication takes place efficiently and robustly, by watching and managing network load,providing redundant connections between sites, and handling changes in transmission standardsthat take place when crossing national and continental borders. While many devices – includingbeepers, faxes, and telephones – are connected to the telephone network, they all have limitedcapabilities: they can offer and accept calls, and during a call they can send and receive data.

Compare these capabilities to those found in our anticipated global distributed system. Thecomponents involved in this network are more complex than the standard telephony interface,though the analogy for services is valid. Conference calls are a good model for short-lived virtualnetworks of objects. A fax machine is a typical example of a generic non-computer I/O devicethat might participate in a distributed system. Call forwarding, caller id, beepers, voice mail,and answering machines are all analogous services as well.

Our visualized object network and the telephone network share three features: there are alarge number of addressable entities, it is possible to connect any arbitrary group of entitiestogether into a virtual network, and the infrastructure supports large numbers of concurrentvirtual networks.

However, objects are different from telephones in several ways:

• There are many more classes of objects than there are “classes” of telephones and telephone-like devices.

2.5. DISTRIBUTED OBJECTS AND VIRTUAL NETWORKS 19

• The persistent state of an object can be substantial. Although a telephone has no persistentstate, voice mail offers temporary state.

• An object can have multiple interfaces with each interface accessible only by authorizedobjects. The telephone network only has a hint of such a notion – for example, multiplepurpose devices like new generation “smart” cellular phones.

• An object can participate in multiple virtual networks concurrently. A telephone cannotparticipate in multiple conversations; call waiting requires the user to do call multiplexinghimself or herself.

• The lifetime of a virtual object network “conversation” can vary from milliseconds to years.Telephone conversations do not last years, even when a teenager is involved.

• Objects may be found by name as well as by attribute, at the very least. Telephonesusually have a single name attached to them, the dialing number, and a single attribute,the person to whom the telephone is registered.

In the worldwide telephone network, a conference call can be set up among any arbitrary groupof telephones. Likewise, in the WON, a collaboration can be set up by connecting together agroup of objects into what we call a virtual network. The virtual network is created when thecollaboration is requested and is deleted when the collaboration terminates. The durations ofvirtual networks vary over a much larger range than the duration of telephone calls. The WONshould support millions of concurrent virtual networks just as the telephone network supportsmany concurrent conversations. The WON should also support a whole range of devices anduses like the telephone network.

2.5 Distributed Objects and Virtual Networks

So far, our discussion has focused on distributed system concepts. Now, we briefly describe theideas of distributed objects and virtual networks, which are also fundamental to our II implemen-tation.

2.5.1 Objects

Objects are groups of data with associated methods to query and modify that data. Objectshave the three primary properties: encapsulation, polymorphism, and inheritance.

Encapsulation. Encapsulation allows an object to have an exposed interface to the outsideworld, with a complementary private implementation that conforms to that interface. In adistributed system, any object that implements a given interface can be replaced with any otherobject that implements the same interface.


Inheritance. Generally, inheritance allows a developer to construct a new object from theinterfaces and implementations of existing objects. A “child” object inherits from one or more“parent” objects, through class inheritance and/or type inheritance. With class inheritance,implementations are inherited, so that the behavior of a child object defaults to the parentobject behavior if it is not overridden. With type inheritance, interfaces are inherited, so that“subtypes” of a parent type are contractually bound to implement the parent’s interface, but donot necessarily reuse their parent’s code.

Polymorphism. Polymorphism allows an object to specify an interface that can handle multi-ple types, reacting accordingly to different types and values. A system that has multiple objectsresponding to the same message – based on its type and value – is analogous to a polymorphicsystem.

2.5.2 Distributed Objects

A distributed object is an object that can communicate across a network with other objects,through remote method calls or message passing. Objects can be single threaded or multi-threaded. Some systems permit objects to maintain state across instantiations. Because theyare written in Java, distributed objects in the II are persistent, multi-threaded, and platform-independent. Distributed objects extend the ideas of encapsulation, inheritance, and polymor-phism.

Encapsulation. With distributed object systems, encapsulation is extended. First, an object’sstate fully encapsulated from the outside world, so that the only way an object A can cause achange in the state of another object B is for A to communicate with B by sending a messageto it or calling a method on it. A thread in one object cannot refer to, have a reference for,or modify, the state of any other object. Second, encapsulation in distributed systems allowslocation transparency. An object can have a reference to a remote object with which it cancommunicate, but it does not need to know the actual physical location of that object.

Inheritance. Notions of class and type inheritance still hold for distributed objects, thoughthere are new issues that need be taken into account. One such issue is method invocationoverhead (due to network latency and bandwidth); if a delegation model is used, one must takeinto account the fact that each additional method call, unless optimized or short-circuited, bumpsthe delay in response significantly due to network issues. Three more factors that come into playwhen dealing with distributed object inheritance are scoping issues (note the scoping rules forJava, for instance, and how they differ from C++), engineering practices (the implied “super”in constructors, for instance), and lack of awareness of locality (in dealing with network errorsfor method invocations and the like).

Polymorphism. In distributed object systems, the concept of polymorphism extends to thenetwork interface. An object receives and responds to messages, which are normally objects

2.5. DISTRIBUTED OBJECTS AND VIRTUAL NETWORKS 21

themselves, of various types in exactly the same manner that local objects respond to methodcalls with parameters of various types. In addition, multiple distributed objects of different(though usually related) types can receive and respond to messages of the same type, actingpolymorphic with respect to the message’s network interface.

2.5.3 Virtual Networks

A virtual network is a set of objects that are related to, and aware of, each other, often to performa particular task. One can view a virtual network as a transaction among a set of distributedobjects, where the objects involved in the transaction were not known before the transaction wasinitiated.

A virtual network can be represented as a labeled directed graph in which the vertices areobjects, and the edges are directed from the output channel of an invoking method to the inputchannel of an object is being invoked. In our system, these channels are the outboxes and inboxesdescribed in chapter 3. The endpoints of the edges are labeled with the names of the channelendpoints and the edge is labeled with the type or types of the messages that are valid onsaid channel. Two-way communication between objects is represented by bi-directional directededges. It is not necessary that every outbox be bound to some inbox, nor that every inbox bebound to some outbox in each virtual network.

Each object has two special named inboxes: the exception inbox and the management inbox.An object can receive requests to connect itself to other objects through its management Inbox.A virtual network is created as follows: A singular object wishes to create a virtual network,this object is called the initiator of the virtual network. The initiator of a virtual networksends messages to the Management Inboxes of the collection of objects with which it needs tocollaborate, requesting them to connect to other objects in the collection. After the initiatorreceives messages from all the objects in the collection that they have connected themselves, theinitiator sends a start message to each object which then proceed with the computation. If thevirtual network cannot be instantiated an exception is raised at the initiator via its ExceptionInbox which then takes appropriate action. The virtual network can be specified and instantiatedgraphically. After the collaboration is completed, the virtual network is deleted by having eachobject delete appropriate bindings of its outboxes and delete appropriate mailboxes (channelendpoints).

The duration of virtual networks vary; some need to be created very rapidly (within a fractionof a second), some are of medium duration (minutes to hours), and others persist for a very longtime (months to years). An example of a virtual network that has to be created rapidly is anetwork that connects the objects of a soft real-time collaborative group of researchers. Anexample medium duration virtual network is a crisis management team. A long-term networkmight be a group of universities that are collaborating on a multi-year ARPA grant.


2.6 Infospheres Components

The II has several components: djinns, the djinn communication layer, sessions, Djinn Masters,and infospheres.

2.6.1 Djinns

A djinn is the fundamental component in the Infospheres Infrastructure. Djinns are componentsin the classical sense: they are distributed applications of varying size that perform specific tasksby working in tandem with other distributed services, djinns, or other distributed objects. Djinnshave well-defined interfaces that allow them to be accessed by other djinns, and can be extendedthrough encapsulation and aggregation. Djinns are written using the Infospheres Infrastructurepackages; alternatively, they can be dynamically generated with the Djinn Initiator and DjinnGenerator GUIs (which are under development and not part of this release).

Djinns can be used to encapsulate a variety of services: simple C, C++, and Fortran pro-cesses, distributed CORBA and COM objects, object libraries and frameworks, legacy businessapplications written in older languages or systems such as COBOL and MVS, traditional DBMSand filesystems, and non-traditional arbitrary processes with deterministic interfaces. Djinns areprimarily used to compose sessions.

Djinns can be multi-threaded, persistent, and can migrate (in a restricted manner today).Djinns run in one of three “execution modes” (basically per instance, per object, and mutualexclusive modes) and can have visual interfaces so as to interact with a user.

We named our distributed components djinns for several reasons. First, we have the definitionof a djinn, (alternatively spelled djin, djinni, genie, jin, or jinni), that of supernatural spirit thatoften takes human (and other) forms and serves its summoner, often exercising supernaturalpower. We enjoyed visualizing distributed components as djinns; entities that work for andwith you to accomplish goals, sometimes acting on your behalf. Second, there is a whole host ofinteresting phraseology that derives from the use of the term; one can performs various operationson djinns to control them: summon, invoke, dispell, query, demand — all terms straight out ofmyth but applicable to the creation, use, and destruction of distributed objects. Finally, thereis the acronym: Distributed Java Infosphere Network Node.

2.6.2 Djinn Communication Layer

The generic djinn communication layer is based on asynchronous messages of arbitrary size andtype. These messages are sent to and from djinns through the use of Inboxes and Outboxes,collectively known as mailboxes, as discussed in chapter 3. The maildaemon is the object,unique to each djinn, that controls the flow of messages through the djinn’s mailboxes. It routesincoming messages to the appropriate mailbox, and ships outgoing messages to the correct targetdjinn. The maildaemon ensures that all messages are ordered point-to-point, and that there isno duplication, loss, or corruption of any message.

2.6. INFOSPHERES COMPONENTS 23

One can exert a fine grain of control on mailboxes to provide typed message streams, mes-sage inheritance between mailbox types, or source-controlled routing of messages. We supplyasynchronous messaging as the base communication mechanism of the Infospheres Infrastructurebecause it is a fundamental messaging construct. We layer on top of it other familiar mechanismslike synchronous, typed, or high-throughput messaging and remote method calls.

2.6.3 Sessions

A session is our primary compositional unit for reasoning. A session is a collection of processes,in an abstract sense, composed in parallel – that is, a session is a reified virtual network. Asession is specified in terms of the precondition and postcondition predicates of its componentprocesses, thus reasoning on sessions is possible. Sessions can be composed using sequentialand choice composition, and we reason about sessions using theory from the field of sequentialprogramming.

From another point of view, a session can be viewed as a generic transaction between a setof distributed active objects where the participants in the transaction are not identified beforethe transaction commences. Often, a session is constructed to fulfill a very specific task in thesystem.

Distributed applications can be structured by nesting processes and sessions, and the Info-spheres Infrastructure supports such capability. For example, a developer can use the DjinnMaster (see next paragraph) to design a session as a directed graph, whose nodes are djinn (de-signed using the Djinn Generator), and whose edges are bindings between mailboxes (constructedusing the mailbox package, see the later description). The Djinn Master can initiate sessionsdescribed in such a manner.

2.6.4 Djinn Masters

The Djinn Master is responsible for the instantiation of, and the initial communication to,persistent djinns in a distributed application or session. The Djinn Master maintains a table ofcurrent djinns running; if a summon message is sent to a djinn that is not currently running (ordoes not currently exist), the appropriate djinn is thawed (or initiated) and executed, and themessage is forwarded to the djinn.

This mechanism is similar to the BOA (Basic Object Adaptor) of CORBA. We provide threeserver models: that of server per request, that of persistent server per session, and that of amutually exclusive server per session.

Note that the Djinn Master is much more lightweight than a CORBA ORB and it is moreflexible since it can initiate arbitrary processes whether or not they conform to the InfospheresInterface specification. We have a prototype Djinn Master available in Java.

The Djinn Master is a djinn like any other. It can accept messages, service requests, and canbe summoned.


2.6.5 Infospheres

Infosphere is a term coined by the Air Force; a person’s Infosphere includes the collection ofinstruments, appliances, computing tools, services, and people accessible from that person’senvironment, wherever it may be physically located (for example, in the office or on an airplane).Djinns make Infospheres constructible: an Infosphere is a personal collection of related djinnsthat are applied by a person to accomplish a particular task.

For example, as I write this document, I am in paper-writer mode and I use a specific set oftools: emacs, framemaker, a Web browser, LATEX, and xdvi. These tools can all be encapsulatedwith djinns to become part of my Paper Writer Infosphere. Later, when I correspond withcolleagues, I will be in Email/Letter-Writer Mode, and my set of tools will differ slightly. Stilllater, after I have had a pot of coffee and a few candy bars, I’ll be in Software Developer Modeas I write, compile, test, and debug source code. using emacs, javac, java, javadoc, and othertools, which can all be encapsulated in djinns in a new Infosphere! We will be providing toolsin the future to support the notion of Infospheres in an integrated fashion (tying in with yourdesktop and browser).

2.6.6 Fundamental Problems in Distributed Objects

There are many fundamental computer science problems in designing the worldwide object net-work described in section 2.4, but the Infospheres research group focuses on four main issues:

1. What is a persistent communicating object and how is it specified?

2. What is a virtual network of communicating objects?

3. How can standard network-centric technologies be exploited in building the object network?

4. How can the object network be implemented efficiently?

2.7 Where to Go Next

In chapter 3, we describe our communication layer, the package info.net, which provides mail-boxes and messages. In chapter 4, we explain how to use djinns to build distributed systems.Djinns can be managed automatically with Djinn Masters, discussed in chapter 5.

Chapter 3

Communication using info.net

The info.net package allows communication among Java programs over the Internet, providingreliable message passing among typed mailboxes. The communications layer of the package isimplemented using UDP sockets from java.net. In this chapter, we highlight the info.net

package, including short discussions of the main classes, example programs, and known imple-mentation anomalies.

The info.net package is valuable in and of itself for developers who want to write net-worked Java programs. You can use it without using packages like info.djinn (chapter 4) andinfo.master (chapter 5).

3.1 A Brief Overview of the info.net Package

info.net provides a simple layer to support the development of Java applications running ondistributed machines that communicate using message passing over the Internet.

The package provides the user with a collection of objects that implement the familiar mailbox-and-messages metaphor we all use every day through the Post Office. By this model, wheneverwe want to send a letter to someone, we write the letter and address it, and then give it to ourlocal post office, which handles delivering the letter to the addressee’s post office, which in turnhandles delivering the letter to the mailbox (and person) at that address. With info.net, theletters are message objects, the address is its place on the Internet, the local and remote postoffices are maildaemons, and the post offices deliver mail to mailboxes.

In the postal system, each person has one or more mailboxes (where s/he lives, where s/heworks, and so on), each mailbox has a globally unique address that can be written on envelopesas the destination for a letter, and any person in the world can attempt to send letters to anymailbox. Similarly, using info.net, each program in the distributed system has a collection ofmailboxes, each mailbox has an Internet-wide unique address called a place, and any programon the Internet can attempt to send messages to any mailbox.

Messages. Messages are objects that have methods to write to and read from data streams(respectively, serialization and de-serialization methods). All objects that are sent from one

25

26 CHAPTER 3. COMMUNICATION USING INFO.NET

Java program to another using info.net are subclasses of the Message class. An object thatis sent by a program is first converted into a String, then sent across the network, and finallyreconstructed back into its original type by the receiving program. Java methods are used toconvert an object to a string and to create an instance of the sending object at the receiver.

Mailboxes. Mailboxes come in two basic flavors: outboxes and inboxes. Outboxes ship mes-sages to target addresses without blocking the local program. Inboxes have two modes of oper-ation: an inbox’s owning program can suspend, waiting on a message to arrive at it, or inboxescan accept and enqueue messages locally (in the background) until its owning program checksfor them. Conceptually, think of a mailbox as locally unique identifier for a queue of messagesthat can be accessed directly only by the object that owns it.

Inboxes and Outboxes. Each Java program can have any number of inboxes and outboxes.Inboxes and outboxes are implemented as message queues; that is, a program can append amessage to the tail of one of its outboxes, and a program can remove the message at the head ofone of its inboxes. Each inbox has a globally unique address called a place (discussed later).

An outbox can be bound to an arbitrary number of inboxes; likewise, an inbox can be boundto by an arbitrary number of outboxes. During its execution, an object can change the bindingsof its outbox(es) dynamically.

MailDaemon. A maildaemon handles the intricacies of the communication layer, managing aprogram’s mailboxes. Think of it as the local post office, with the zip code being the machinename (IP or DNS address) and port number on which it runs, and individual mailboxes beingthe P.O. boxes at the post office for that zip code. MailDaemon runs in the background, receiv-ing, sorting, and filing messages in the appropriate mailboxes. MailDaemon also fires an eventwhenever the inbox is not empty, so its owning program can be notified of incoming messages.

If a message has been sent to an incorrect address (or an address to which it is not autho-rized to be sent), MailDaemon returns the message to the sender in the form of an exception.MailDaemon also ships outgoing mail, interacting with the maildaemon of another program toensure message reliability, non-duplication, and proper ordering from a given outbox to a giveninbox.

Places. A mailbox address is called a place. A place consists of three main parts: the localhost machine IP address, the number of the local port being listened on by the maildaemon formessages, and a String name called the mailbox name. A Place points to a globally uniquemailbox on the Internet.

Methods Invoked on Outboxes. The application-layer methods that can be invoked onoutboxes are:

3.1. A BRIEF OVERVIEW OF THE INFO.NET PACKAGE 27

1. Create an outbox of a specified type (with an optional string name); this method returnsthe globally unique id of the outbox that is created. An exception is raised if the objectalready has a mailbox with that specified name.

2. Delete an outbox specified by globally unique id or name.

3. Append a local variable message to the tail of an outbox. This will have the effect ofsending a copy of that message along each output channel connected to the outbox. If thismessage is not delivered within a specified time, an exception is raised.

4. Change the set of inboxes to which an outbox is bound, subsequently adding, removing, orredirecting a given binding. There is a directed FIFO channel from each outbox to eachinbox to which it is bound.

5. Check the set of inboxes to which an outbox is bound.

Methods Invoked on Inboxes. The application-layer methods that can be invoked on in-boxes are:

1. Create an inbox of a specified type (with an optional string name); this method returns theglobally unique id of the inbox that is created. An exception is raised if the object alreadyhas an mailbox with the specified name.

2. Delete an inbox specified by globally unique id or name.

3. Change the set of objects authorized to send messages to an inbox.

4. Check whether an inbox is empty.

5. Suspend execution until an inbox is nonempty, and receive the message at the head of theinbox into a local variable, deleting this message from the inbox. This is the only methodon mailboxes that can suspend execution.

Sendboxes and Receiveboxes. As implemented, an inbox is an abstract entity that can beused to develop custom message-receiving mailboxes, and an outbox is an abstract entity thatcan be used to develop custom message-sending mailboxes. The simplest versions of inboxes andoutboxes that can be used in distributed programs are receiveboxes and sendboxes, respectively.

A receivebox receives messages from a maildaemon and files them away in a queue. Messagescan be recovered using the receive method. If there are no messages in the queue, the receive

blocks until there are (unless a timeout period is specified, in which case the receive returnsnull if no message arrives within the timeout period). There are other methods that allow forgreater control over the receivebox, such as an empty method that checks whether the queueis currently empty, and a waitForMessage method that waits for a message to arrive in thequeue, with optional abilities to set finite times. In addition, two other variables are associatedeach message: the local time stamp (which allows for complete ordering of all Messages received


locally by time of arrival), and the return address (which is the address of the mailbox that sentthe message). Use the time and from methods, which act on the oldest message in the queue,to access these two variables. If you remove the Message from the queue, you lose the time andreturn address of the Message.

So, the methods that can be called on a receivebox are:

• insertMessage is the method that handles new messages as they arrive. It puts a messagein the queue with the specified timestamp and the specified return address. This methodis inherited from Mailbox, and normally you will not have to use it. You only need todefine insertMessage when you want your receivebox to deal with new messages whenthey arrive in some special way.

• waitForMessage waits for a message to arrive at the queue of the receivebox.

• receive pulls a message from the head of a receivebox’s queue. Note that when a receiveis called, the message is removed from the queue, so that time and from can no longer beused on that message. receive may suspend indefinitely if no timeout is specified.

• time returns the time stamp of the message on at the head of the receivebox’s queue.

• from returns the origin of first message on the receivebox’s queue.

• nonEmpty returns true the queue has any messages in it, false otherwise.

• empty returns false the queue has any messages in it, true otherwise.

• name returns the name of the receivebox.

A sendbox class allows for the connection to one inbox at a time. Once connected to anreceivebox using the bind method, a sendbox can push messages to that receivebox. At anypoint a program can dynamically re-bind to another receivebox using the bind method, so anymessages sent will be sent to the newly bound inbox. Bindings are done by handing the bind

method a Place object that has the address of the desired Inbox.In addition to constructors, a sendbox has the following methods:

• insertMessage is the method that handles new messages as they arrive. Even sendboxescan get incoming mail telling them information (for example, their messages have beenrefused), so they need an insertMessage call, too. insertMessage puts a message inthe queue with the specified timestamp and the specified return address. This methodis inherited from Mailbox, and normally you will not have to use it. You only need todefine insertMessage when you want your receivebox to deal with new messages whenthey arrive in some special way.

• bind attaches a sendbox to a specified destination place.

3.1. A BRIEF OVERVIEW OF THE INFO.NET PACKAGE 29

• destination returns the current destination of messages sent through this particular send-box.

• send sends a message to the currently bound destination. If there is no currently bounddestination, the method will throw a runtime exception.

Note that a sendbox can only send to a single inbox, and it does not synchronize that send.Other outboxes (such as broadcastboxes and syncoutboxes) are included with info.net to suitthese needs. Note also that a receivebox does not know (and needs not know) what outboxesacross the Internet have attached to it; it can only ascertain from individual incoming messageswho the senders of those messages were.

Communication. info.net guarantees that objects sent between any two mailboxes willarrive in order, without duplication, and with no skipping. Object ordering when different boxessend to a single receiving box is not deterministic.

The info.net communication layer itself removes the message at the head of a non-emptyoutbox, and delivers a copy of the message to each inbox to which it is bound.

Message delays are finite; that is, a message will not remain in transit between an outboxand an inbox indefinitely without an exception message being delivered to the sender. Thecommunication layer is fair in the sense that it delivers every outbox message to the appropriateinbox(es) in finite time. Messages from a particular outbox to a particular inbox are deliveredin the order they are sent; however, a later message from one outbox to a particular inbox mayovertake an earlier message from a different outbox to the same inbox.

Associated with each inbox is one or more filters that describe which set of objects are (andare not) authorized to send messages to it. The communication layer ensures that the messagesof unauthorized objects do not get delivered to that inbox; instead, an exception message isdelivered to the inbox in its place.

The communication layer also provides facilities for remote class loading, either with securityprovisions or without them.

Objects. As implemented in Java, an object can have a single thread or be multi-threaded.The threads of an object can change the local state (the values of its variables) of the object,create mailboxes for the object, and execute methods on its mailboxes. A thread of one objectcannot modify the local state of another object, create a mailbox for another object, or modifythe state of a mailbox of another object. The communications layer can modify the states ofmailboxes by deleting messages at the head of nonempty outboxes, depositing copies in inboxes,and delivering exception messages; the communications layer does not modify local states ofobjects.


3.2 Using the info.net Package

To use info.net, place import info.net.* in the header part of the relevant Java sourcefiles. In addition, tell the Java interpreter and compiler where the info.net package classesare by setting the CLASSPATH environment variable to the appropriate value. Remember to setCLASSPATH to the root of the info hierarchy, not necessarily to the directory holding the actualclass files.

First, we present a “Hello, World” example that illustrates the basic components of theinfo.net package — maildaemons, mailboxes, messages, and places. Our “Hello, World” consistsof a sending program and a receiving program.

3.2.1 Hello, World - the Sender

The sending program takes three command-line arguments (the machine name, port number,and mailbox name to which to send the message), turns them into a place, and sends the string“Hello, World” as a message to that place.

Note that Java requires that you initialize a MailDaemon or Receivebox to null.

import info.net.*;

public class HelloWorldSend {

// args[0] is the IP address or machine name to send to

// args[1] is the port number on that machine

// args[2] is the local mailbox name (a String) at that port

public static void main (String[] args) {

// For scoping to work in try/catch clauses, declare MailDaemon first.

MailDaemon myMailDaemon = null;

// Create a new MailDaemon to manage all of our Mailboxes.

// We do not pass a port to the constructor, so it uses the default port, 9876.

try

{

myMailDaemon = new MailDaemon ();

}

catch (MailDaemonException exception)

{

exception.printStackTrace ();

System.exit (1);

}

// Create an outgoing Mailbox for sending messages.

Sendbox mySendbox = new Sendbox (myMailDaemon);

// Use a three-string Place constructor.

Place targetPlace = new Place (args[0], args[1], args[2]);

// Bind mySendbox to the targetPlace so messages we send

// through our Mailbox will go to that address.

3.2. USING THE INFO.NET PACKAGE 31

mySendbox.bind (targetPlace);

// Create a message to send. StringMessage is a child of

// Message used for sending Strings.

Message myMessage = new StringMessage ("Hello, world!!!");

// Send the message. This method does not block.

// myMailDaemon ships the message over the wire in the background.

mySendbox.send (myMessage);

// Force the thread to block until the message has been

// successfully delivered to its target address.

// Since threads can be interrupted by other threads,

// use a try/catch block here.

try

{

// Waits until all messages in myMailDaemon are flushed.

myMailDaemon.waitUntilFlushed ();

}

catch (InterruptedException exception) { }

} // end main

} //end class HelloWorldSend

If you compile and run this code with the proper command line arguments representing amachine name, port, and mailbox name, you will notice the program seems to just sit there,doing nothing. Actually, the program is continually trying (and failing) to send the message tothe recipient mailbox. As a result, we need a receiver program.

3.2.2 Hello, World - the Receiver

The receiving program takes two command line arguments (the port number on which to listen,and the mailbox name at that port), creates a mailbox waiting at the proper place, and waitsfor a message there.

import info.net.*;

public class HelloWorldReceive {

// args[0] is the port number to listen on

// args[1] is the Mailbox name at that port

public static void main (String[] args) {

// For scoping to work in try/catch clauses, declare

// the MailDaemon and Receivebox first.


Receivebox myReceivebox = null;

// Create a MailDaemon that listens on a specific port.

// If the port is already in use, an exception is thrown and handled.


try

{

myMailDaemon = new MailDaemon (Integer.parseInt (args[0]));

}


{


System.exit (1);

}

// Create an incoming, named Mailbox for receiving messages.

// If the Mailbox name is already in use, an exception is thrown

// and handled.

try

{

myReceivebox = new Receivebox (myMailDaemon, args[1]);

}


{


System.exit (1);

}

// Wait for a message to arrive. This method blocks until a message

// arrives at myReceivebox. If we desired, we could do other work

// and occasionally poll myReceivebox with the myReceivebox.empty() call.

try

{

myReceivebox.waitForMessage ();

}

catch (InterruptedException exception) { }

// Determine from where and when the received message was sent.

Place fromPlace = myReceivebox.from ();

// Retrieve the message from myReceivebox.

Message myMessage = myReceivebox.receive ();

// Print the results.

System.out.println ("Message \"" + myMessage + "\"");

System.out.println ("was received from " + fromPlace);

} // end main

} // end class HelloWorldReceive

Now you can compile these programs and run them. For example, on flute.cs.caltech.edu

you can run

java HelloWorldSend harmonica.cs.caltech.edu 6060 adambox

and, on harmonica.cs.caltech.edu you can run

java HelloWorldReceive 6060 adambox

Then on machine harmonica you will get the following output

3.2. USING THE INFO.NET PACKAGE 33

Message ‘‘Hello, World!!!’’

was received from flute.cs.caltech.edu 6060 __1.

Note that the 1 is the locally unique name given to the sending mailbox on machine flute

by its maildaemon, since the user did not specify one.

3.2.3 Hello, World - Revisited

We can tighten the code using some variants of the info.net package.

// Code for Sender

import info.net.*;

class HelloWorldSend2 {

public static void main (String[] args)

{


try { myMailDaemon = new MailDaemon (); }

catch (MailDaemonException e) { System.exit (1); }

Sendbox mySendbox =

new Sendbox (myMailDaemon, new Place (args[0], args[1], args[2]));

mySendbox.send (new StringMessage ("Hello, world."));

myMailDaemon.waitUntilFlushed ();

}

} //end class HelloWorldSend2

// Code for Receiver

import info.net.*;

class HelloWorldReceive2 {

public static void main (String[] args)

{


try { myMailDaemon = new MailDaemon (Integer.parseInt (args[0])); }

catch (MailDaemonException e) { System.exit (1); }

Receivebox myReceivebox = null;

try { myReceivebox = new Receivebox (myMailDaemon, args[1]); }

catch (MailDaemonException e ) { System.exit (1); }

System.out.println ("Message: \"" + myReceivebox.receive() + "\".");

}

} //end class HelloWorldReceive2

Now you can compile these programs and run them. For example, on flute.cs.caltech.edu

you can run

java HelloWorldSend2 harmonica.cs.caltech.edu 9942 blahbox

and, on harmonica.cs.caltech.edu you can run


java HelloWorldReceive2 9942 blahbox

Then on machine harmonica you will get the following output

Message ‘‘Hello, World.’’.

Note that if a maildaemon is running on harmonica at the correct port, but no Receiveboxcalled blahbox is managed by the mail daemon, then the program at flute will continuouslycomplain about not being able to reach blahbox:

__1 not getting to harmonica 9942 blahbox because of DenyMessage:

(4)No portlet of that name

You should now have a basic understanding of how the info.net package works. In the nextsection, we highlight info.net in more detail to supplement the online documentation.

3.3 A More Detailed Look at info.net

Now we delve deeper into some details of the info.net classes that network application devel-opers will find useful.

3.3.1 Mailboxes

Each mailbox has an associated MailDaemon object that manages it. In general, an applicationwill have a single MailDaemon to manage all its mailboxes. Each mailbox has a locally uniquestring name that distinguishes it from the other mailboxes managed by the MailDaemon. Amailbox name should have no whitespace in it whatsoever. The Mailbox class implementsaddress maintenance and name maintenance. All varieties of mailboxes are derived from thisbase class.

Note that when making a mailbox, the insertMessage method needs to be defined, since itis the method that handles new messages as they arrive. Even outboxes can get incoming mailtelling them information (for example, their messages have been refused), so this method shouldbe defined for them as well.

Places. A Place is the globally unique name identifier for mailboxes of all sorts. It is mainlyused to send messages to specific inboxes. A Place has three components: a machine address (forexample, an InetAddress object such as ”tuba.cs.caltech.edu”), a port number, and a mailboxname (a String). There are a variety of constructors for a Place; please consult the onlineJavadocs for descriptions of them to determine the one most suitable for any given application.

Removing Mailboxes. Deleting mailboxes can be tricky, because you have to make sure theJava program is finished with them, especially taking care that the program has extracted all ofthe messages from a mailbox before removing the mailbox. To delete mailboxes, use the destroymethod.

3.3. A MORE DETAILED LOOK AT INFO.NET 35

3.3.2 Inboxes to Handle Receiving Messages

An Inbox receives messages from its maildaemon and files them away in a queue. These messagescan be recovered using the receive method. If there are no messages in the queue, the receive

method blocks until there are (or until a specified timeout period has elapsed). There are twoversions of receive, one of which allows a specifiable timeout period: if a message is receivedwithin the timeout period, it is returned (just as in the non-timeout version of the call); otherwise,null is returned.

Other methods on an inbox include empty, method which checks whether the queue is cur-rently empty, and waitForMessage, which waits for a message to arrive in the queue (withoptional arguments to set finite time limits).

In addition, there are two other pieces of data associated with any given message: the localtime stamp, which allows for a complete ordering of all messages received locally by time ofarrival, and the return address, which is the address of the mailbox which sent the message.To get these two bits of information, use the time and from methods. Note that to use thesemethods, they must be invoked before the receive, which physically removes a message fromthe inbox queue. Since these methods act on the oldest message in the queue, when you removethat message, you lose that information.

Also, the name method returns the name of the mailbox. And, please consult the Javadocsfor specific information about the methods and constructors for inboxes.

In practice, you will not use inboxes directly in your programs. Instead, you will use one ofthe info.net extensions of inboxes, or extend inbox with a class that implements your desiredfunctionality. The provided inbox extensions in info.net are Receivebox, SyncInbox, andReceiveSet.

Receiveboxes. Receivebox receives messages from a maildaemon and files them away in aqueue. Receiveboxes have the receive, empty, waitForMessage, time, from, and name methodsas inboxes. Currently the Inbox and the Receivebox classes are the same, except that the Inboxis a base class for all types of inboxes, so you should use Receivebox in the applications youwrite.

SyncInboxes. Whereas a Receivebox just pulls messages off its input queue, a SyncInbox

sends acknowledgment messages to the sender whenever a message is pulled from the queueusing the receive method. The sending mailbox should therefore be a SyncSendbox so it cangracefully deal with this acknowledgment, as illustrated by the example in section 3.4.6. Theacknowledgments sent are DenyMessage (DenyMessage.ACK) messages, which are described inthe Javadocs.

ReceiveSets. A ReceiveSet allows the collection of multiple inboxes into a set that can waitfor a new message or get the oldest message. Mailboxes can be added and removed from this seteasily, allowing for a dynamic collection of receive mailboxes. Receiveboxes are not meant to besynchronized. The example in section 3.4.8 illustrates how to use ReceiveSet.


The waitForMessage method waits for the set to have a message in one of its membermailboxes, and then returns a reference to that member. It first checks to see if any of themailboxes in the set have a message. If there is one, it returns the Inbox that contains theoldest message; standard inbox operations can then be called on that inbox. Otherwise, thewaitForMessage call waits until one of the mailboxes has a message, and then at that point itreturns a reference to that mailbox.

Note that waitForMessage will block until there is a message in one of the receiving mailboxesin the set. So, if there is no mailbox in the set, then this function blocks forever unless a timeoutperiod is specified (in which case it returns null if no message has arrived within the timeoutperiod).

3.3.3 Outboxes to Handle Sending Messages

An Outbox is the base class for all mailboxes that send messages. It implements the doSend

method, which sends a message to the given Place. Note that you should not change themessage after sending it. The message should be considered to have been given to the info.net

package at the point of sending it. If you change it after sending it, the message arriving at theother end may in fact be changed.

Please consult the Javadocs for specific information about the methods and constructors foroutboxes. In practice, you will not use outboxes directly in your programs. Instead, you will useone of the info.net extensions of outboxes, or extend outbox with a class implementing yourdesired functionality. The provided outbox extensions in info.net are Sendbox, SyncOutbox,Broadcastbox, and Multicastbox. Before we talk about these types of outboxes, we first discussDenyMessages.

DenyMessages. DenyMessages are sent to a sending mailbox when the receiving end of aconnection does not accept an arriving message. It is also used by synchronized mailboxes tosend acknowledgments of message receipt (given by its ACK value).

The DenyMessage constructor method handles sending the appropriate reason for messagedenial:

• ACK — acknowledgment for sent message.

• DENY — denial by a filter.

• NO PORTLET — no portlet of that name.

• CORRUPT MESSAGE — message data could not be parsed on the target machine.

• ACCESS ERROR — message sent was not a public class.

• WRONG MAILDAEMON — message was sent to the maildaemon with an id which wasnot present.


To use DenyMessages, any subclass of Outbox should override the MessageDenial method,which is called whenever a DenyMessage arrives at that Outbox. The parameters to MessageDenialare the DenyMessage itself (holding as its data the reason why the message was denied), and thefailed address.

Sendboxes. The Sendbox class allows for the connection to one inbox at a time. When youhave connected to an inbox using the bind method, you can send messages as desired to thatmailbox. At any point, you can re-bind to another receive mailbox using the bind method, andthen any messages sent will be sent to the newly bound mailbox. Bindings are done by handingthe bind method a Place object that has the address of the appropriate inbox.

The present bind does a bind without considering the type of the endpoints of the channel.You can use security and filter features to ensure that only proper messages get through. We’lltalk about security and filter features in sections 3.3.8 and 3.3.6, respectively.

SyncOutboxes. A SyncOutbox, along with its counterpart the SyncInbox, form a synchro-nized connection. When one sends a message using a SyncOutbox, it blocks until the receiver hastaken the message out of its queue using the receive method of the SyncInbox. The SyncOutboxwill wait forever if the receiver does not send acknowledgments, so it is very important that thereceiver be a SyncInbox.

It is possible to have a SyncOutbox block for only a finite, specified amount of time. In thiscase, the send method returns whether the time expired or if the message was acknowledged,as illustrated by the example in section 3.4.6. The acknowledgments sent are DenyMessage

(DenyMessage.ACK) messages, which are described in the Javadocs.

Broadcastboxes. A Broadcastbox is a single mailbox that maintains a set of destinationPlaces. The user can add or remove Places, and send messages to all of the Places at once.The Broadcastbox ensures that no Place is duplicated in the set. Repeated adds of the samePlace to (the set of Places associated with a) Broadcastbox has no effect. On a send command,each place in the set receives exactly one copy of the message. Consult the Javadocs for extrainformation. The example in section 3.4.7 illustrates the use of a Broadcastbox.

Multicastboxes. The difference between a Broadcastbox and a Multicastbox is the protocolused for Message transfer: unicast for the former, multicast for the latter. Note that this featurehas not yet been added, so in the current release, these two types of boxes are the same (usingunicast).

3.3.4 The MailDaemon

A MailDaemon, when it is created, labels itself with a timestamp. This timestamp is passed alongwith all messages, so different instantiations of a MailDaemon on the same port and machine canbe told apart. This is done in the background for the most part however. When first sendingto a MailDaemon, the MailDaemon id is left as a “wild character” so any MailDaemon there will


respond. When it responds, the “wild character” is bound to the specific MailDaemon, and if itlater dies and a new one takes its place, an exception will be thrown on the sending end.

Receiving ends will silently accept messages from any MailDaemon. Comparing the twoaddresses will show the difference, but this has to explicitly be done on the user’s part. This isto keep in line with the philosophy of the info.net message passing; any outbox can send toany receiving box, and therefore two separate MailDaemons which lived sequentially on a singleport and machine should be able to, without error, send to a specific receive box.

MailDaemon is implemented as two concurrently running Java threads, MailDaemonIn (han-dling input) and MailDaemonOut (handling output).

MailDaemons and Djinns. A MailDaemon manages the mailboxes of a Djinn (djinns arediscussed in chapter 4). It listens on a port for messages addressed to it incoming mailboxes, andprocesses those Messages by eventually putting them in the inbound queues of the appropriateincoming mailboxes. It also delivers messages from the outbound queues of outgoing mailboxes tothe appropriate incoming destination mailboxes (which can be on a different host). MailDaemonhas a set of background threads running as a daemon, that guarantees reliable, ordered messagepassing. Mailboxes in a djinn are registered with its MailDaemon by the mailbox constructors.

3.3.5 Messages

Message is the abstract class that is the parent of all things sent through the mailboxes. A numberof derived message types are included with the info.net package, such as StringMessage forpassing strings, and NumberMessage for passing numbers.

Any message class can have a URL associated with it. These URLs are sent along with themessages to serve as a globally unique ID. This ensures that if a message arrives at a location,it is either recognized correctly, or is “known to be unknown.” In addition, if a message that isunknown arrives, the remote class loader is invoked (see section 3.3.7), and the class associatedwith the passed message and URL is loaded remotely, if possible. Before doing so, however, theURL is checked with the static URLStringSecurity object of that Message class (see section3.3.8). If you do not set such an object, then one does not exist, so use the getURLChecker andsetURLChecker methods. Otherwise, any URL will be trusted, and if necessary bytecode will bedownloaded from that site and run by the java interpreter as a Message object.

Note that the sending program must not modify a message after it is sent.

Writing New Message Classes. The Message class is used to create new and specializedversions of messages. In general, only two abstract methods need be defined by the creator of anew Message: the writeData and readData methods. In addition, the class needs to be public,and it needs to have a public constructor which takes no arguments.

writeData takes the message and returns an array of bytes which store all the relevantdetails of the message. This array will then be sent to some inbox somewhere, and that willcall the readData method of the message to reconstruct the object. There is run-time typing so


the correct type of object will be built automatically, meaning that you need not worry aboutfiguring out which object is arriving.

readData takes a byte array and builds an object from it. When the method is called,info.net assumes that the byte array was created by the sister method writeData from thesame Message class.

An example of a new message with two integers is

public class MyMessage extends Message {

public int a;

public int b;

public MyMessage( ) { }

public void writeData (DataOutputStream dos)

throws IOException

{

dos.writeInt (a);

dos.writeInt (b);

}

public void readData (DataInputStream dis)

throws IOException, MailDaemonException

{

a = dis.readInt (a);

b = dis.readInt (b);

}

}

If you want to include messages inside messages, write code that calls the readObject andwriteObject methods. For example, to write such a message you would have

message.writeObject (dos);

in the writeData method of the parent object, and to read you would have

message = (MyMessage) readObject (dis);

in the readData method of the parent object. The example given in section 3.4.2 illustratesthe creation of complex message objects.

The “object” in readObject and writeObject is any class outside the java.* hierarchy, inparticular subclasses of the Message class. Normally, you should not need to use readObject andwriteObject; simply implement the reading and writing of data items from and to streams usingmultiple readData and writeData calls. However, when sending and receiving “objects” over thewire, you must call readObject and writeObject from the appropriate readData and writeData

methods. Note that you should never call super.readObject and super.writeObject.


3.3.6 Message Filtering

The Filter class is used by inboxes to check messages before accepting them into the queue.Filters can be used for many things; for example, you can ensure there are only NumberMessagesin the queue. Another example is that you can make the queue only accept messages from aspecific Place. See section 3.4.1 for an example of filtering in practice; see the online Javadocsfor more information about the methods and their usage.

To install a filter in an inbox, use its setFilter method, and pass to it the filter you wantto use.

The CheckMessage method does the actual filtering, determining whether a message/senderpair is acceptable. It takes a message and the place that sent it, and decides whether to acceptor deny that message based on checks of the class, host, and place. If a message fails any one ofthese checks, it is deemed to be unacceptable; otherwise, the mailbox accepts the message.

CheckMessage is the method to override to change the default behavior of Filter. By default,CheckMessage calls SendDenial to send a DenyMessage to the sending mailbox of any messagethat does not pass the Filter, as demonstrated by the example in section 3.4.1.

3.3.7 Remote Class Loading

The MultiURLClassLoader allows classes to be loaded over the network, using the providedURLs and the provided URLSecurity object if desired. This class loader is based on theNetworkClassLoader supplied as an example by the Sun Class documentation under ClassLoader,and makes use of the URLClassFileLoader class. See example 1b in section 3.4.1 for an exampleof remote class loading; see the online Javadocs for more information about the methods andtheir usage.

The addURL method adds a URL to the MultiURLClassLoader’s classpath, if necessary. ThisURL will also be the first to be checked on the next classload. The loadClass method loads aclass, locally or remotely.

3.3.8 Class Loading Security

URLStringSecurity is a URLSecurity that is very flexible, and allows for selection of trustedsites for remote class loading. See the online Javadocs for more information about the relevantmethods and their usage.

URLStringSecurity keeps track of four sets: rejectSet, acceptSet, portAcceptSet, andprotocolAcceptSet. If any rejectSet member appears within in the URL host string, then aremote class load is rejected. Otherwise, at least one of the acceptSet members needs to appearfor the URL string for classloading to occur.

In addition, if the portCheckingFlag is on, then the URL’s port must be in the portAcceptSetto be accepted. Also, if the protocolCheckingFlag is on, then the protocol must be in theprotocolAcceptSet to be accepted.

If the string to compare is to be matched at the beginning or the end of the URL, the toBeginand toEnd methods should be used – see the Javadocs. Port selection can also take place with

3.4. EXAMPLES ILLUSTRATING THE INFO.NET PACKAGE 41

the addPort method.

3.4 Examples Illustrating the info.net Package

The examples in the info.demo.net package each demonstrate one or more features of theinfo.net package. Together, they show how info.net can be used to implement typicalmessage-passing systems.

We already explored the following programs in section 3.2:

HelloWorldReceive.java

HelloWorldSend.java

HelloWorldReceive2.java

HelloWorldSend2.java

Now we explore eight more examples that span the gamut of functionality in info.net. Forbrevity, we do not include the source code for these examples in this documentation, so youshould read and run them online as you peruse this section.

3.4.1 Simple Send and Receive with Filtering

We use the following files:

exampleReceive1.java

exampleSend1.java

SecretInterface.java

UnknownMessage.java

exampleReceive1b.html

exampleReceive1b.java

exampleSend1b.java

Example 1 demonstrates a simple send and receive: the receiving end waits for the sender topass it messages, and the sender sends messages with delays. The line

filter.addAllowedClass (‘‘info.net.NumberMessage’’);

makes the receiver filter out all non-number messages, using the NumberMessage class.Example 1b is an interesting variation. The sender sends an unknown type of user-defined

messages (given in UnknownMessage.java, with URL links to remote load it from the InfospheresWeb site). The MailDaemon in the receiver will remote class load them if possible from theInfospheres site. To verify this, delete the class files for UnknownMessage on the receiving end,but not the sending end. The receiver is an applet rather than an application, so run

appletviewer examplereceive1b.html

run one of the senders with the proper machine name, port number, and mailbox name.


3.4.2 Waiting for Delivery on One of Several Inboxes


example2_Message.java


exampleSend2.java

Example 2 illustrates how a Java program can simultaneously wait for messages from twoincoming mailboxes, servicing the first message to show up on either mailbox.

This example also illustrates how to create complex messages containing other message objectsand multiple fields. The complex message is called example2 Message, and is inherited fromNumberMessage. It holds any other Message as well as a String.

3.4.3 Spamming



exampleSend3.java

Example 3 performs the continual push of messages from a sender to a receiver, otherwiseknown as spamming. Specifically, the sender throws NumberMessages at the receiver as fast aspossible, and the receiver tries to print them to the screen as fast as possible. The numbersincrease sequentially, so the user can see the ordering aspect of the info.net transfer protocol.

This example demonstrates that sending more messages than a receiver can process, clogsthe communications pipe. Therefore, it is highly recommended that you do not spam in thecommunications between the programs you write. There is usually another, more elegant solutionto spamming in any given situation.

3.4.4 Waiting for Delivery on Multiple Inboxes



exampleSend4.java

Example 4 demonstrates the ability for a Java program to wait until two mailboxes have atleast one message in each before processing any messages at all. The sender sends to two separatemailboxes on the receiver, but sends two messages to the first mailbox before sending any to thesecond. Nothing is printed to the screen until both the first and second mailboxes have messagespending.

3.4. EXAMPLES ILLUSTRATING THE INFO.NET PACKAGE 43

3.4.5 A Ring of Message Passers

We use the following file:

example5.java

The single program provided by example 5 implements a node in a potential ring of servers.The command line arguments are the local receive mailbox, and where to send messages whenthey arrive. After setting up the ring yourself (manually running them on distributed machines),programs pass a NumberMessage around, increasing its value by 1 with each receive.

3.4.6 Synchronized Send and Receive



exampleSend6.java

Example 6 demonstrates the synchronized receive and send mailboxes. The sender sendsmessages as fast as it possibly can; however, these messages are staggered (and hence the senderis delayed) by the receiver waiting before taking a message out of a queue synchronously. Thesynchronous message removal from the queue triggers an acknowledgment to the sender, freeingit to do more work (in this case, send more messages).

3.4.7 Places as Messages and Broadcast Mailboxes



exampleSend7.java

Example 7 illustrates using Places as messages and Broadcast mailboxes. The sender is a“server” that broadcasts a message out to all registered receivers. To register, a receiver has tosend its address to the sender’s inbox. Sending an address again removes the receiver from thesender’s broadcast list.

3.4.8 ReceiveSets



exampleSend8.java

Example 8 shows how ReceiveSets work. The receiver sets up three mailboxes and puts twoof them in a set. It then waits for messages on that set alone, ignoring the third mailbox. Thesender sends messages to all three in steady rotation.


3.5 Caveats and Suggestions

In this section, we warn of some of the anomalous behaviors presently in the info.net package,and offer some suggestions for developers.

Note that we are currently redesigning info.net at an object, not an API, level. We providesupport for multiple underlying messaging infrastructures including UDP, TCP, and Multicast inII 2.0. II 2.0 also includes several new interesting features such as message and port metadata,remote procedure calls of various flavors, and event notification and dispatch, and dynamic objectcomposition.

3.5.1 Warnings About the Current info.net

We are presently checking through info.net for race conditions.

Warnings About Timing Issues. The ReceiveSet, when you block for a message, firstchecks to see if any messages are pending, and then waits until a new message comes in. Howeverif a message arrives just after the method finishes checking the boxes, then but before it waits,it will hang forever (assuming no new message comes in).

This is just one race condition we know about; we expect to fix these timing errors for thenext release.

Other Problems with info.net Messages currently have a maximum length of around 60k.II 2.0 supports messages of arbitrary length.

The MailDaemon presently implements a go-back-n message queue window protocol. II 2.0supports a more advanced protocol for efficiency.

Presently, Multicastbox is exactly the same as Broadcastbox. Full multicast support is inII 2.0.

Presently, a MailDaemon will exit if the port and machine it tries to listen on are already inuse. Also note that a RuntimeException will presently be thrown when a process attempts tosend a message to an address where there is nothing listening at the other end.

About Initializing MailDaemons and Mailboxes. Note that Java requires that you ini-tialize a MailDaemon or Receivebox to null.

Warnings About Messages. To create your own message, inherit from the Message class orone of its children and implement the writeData and readData methods. In addition, the classneeds a public default constructor that takes no arguments.

When creating new Message types, make sure the readData and writeData methods and theconstructor are public. Also make sure the class itself is public, or it will not be instantiated onthe receiving end. Some examples of derived messages are StringMessage and NumberMessage.

The “object” in readObject and writeObject is any class outside the java.* hierarchy, inparticular subclasses of the Message class. Normally, you should not need to use readObject and

3.5. CAVEATS AND SUGGESTIONS 45

writeObject; simply implement the reading and writing of data items from and to streams usingmultiple readData and writeData calls. However, when sending and receiving “objects” over thewire, you must call readObject and writeObject from the appropriate readData and writeData

methods. Note that you should never call super.readObject and super.writeObject.

To use the time and from methods, they must be invoked before the receive, which phys-ically removes a message from the inbox queue. Since these methods act on the oldest messagein the queue, when you remove that message, you lose that information.

When using a ReceiveSet, the waitForMessage will block until there is a message in one ofthe receiving mailboxes in the set. So, if there is no mailbox in the set, then this function blocksforever unless a timeout is specified (in which case the function returns null if no message arriveswithin the timeout period).

When using the doSend method of an outbox, note that you should not change the messageafter sending it. The message should be considered to have been given to the info.net packageat the point of sending it. If you change it after sending it, the message arriving at the otherend may in fact be changed.

When making a mailbox, the insertMessage method needs to be defined, since it is themethod that handles new messages as they arrive. Even outboxes can get incoming mail tellingthem information (for example, their messages have been refused), so this method should bedefined for them as well.

Warnings About Killing Programs. Do not kill and restart a program on the same machineand port if you are leaving other programs up which previously sent messages to that location.However if you kill both ends, then you can reuse the ports. (What is happening is the datatables on the live end no longer matches with the fresh, empty data table on the new end, andit gets confused. This is a bug.)

Warnings About Class Loading. The MailDaemon and the MultiURLClassLoader havebeen tested with ftp:, http:, and file: URLs, and with recursive loading. Currently, there isone incompatibility: ftp URLs that point to Macintosh ftp servers running NetPresenz 4.1 (suchas that running on ftp://babylon.caltech.edu/) cause the classloader to hang while closingthe input stream from the URL. We have no idea why this is, but we believe that the problemis not in our code.

If you use the remote class loader to grab a class which has interfaces you don’t know aboutlocally, and then you attempt to interact with that class’s interfaces via the getInterfaces

method of the Class object, you will not only get an error you will get a full thread dump. Thisis a Java error. However, the other interface manipulations work fine. In addition, if you do agetInterfaces() call within the remotely loaded classes, then you can do a getInterfaces calloutside the class after that point. However, be forewarned that the getInterfaces call does notlet the classLoader load the interface classes properly.

Also, the remote class browser does not automatically check any classes for security, meaningthat it can download and run anything unless you explicitly use the URLStringSecurity class.


Warnings About Various Flavors of Java. Some platforms do not implement Java’sDatagramSockets and/or normal sockets correctly (!). In these cases, the info.net packagewill break.

Our version of the Java tool expresso has not compiled the info.net code correctly.

3.5.2 Tips for Developers Using info.net

Here are several suggestions to make development using info.net easier.

Port number selection. Use only numbers above 1024 (below 1024 are reserved). We suggestusing numbers above 6000, excluding 8000, 8001, and 8080 because they are sometimes used asWeb serving ports.

’mailbox not known’ type messages. Make sure the length displayed at the end of themessage is the actual length of the mailbox name (in characters). If it is not, when yoursender is binding to that receive mailbox, it actually has a name with some mystery charac-ters in it. To prevent unnecessary grief, check the SendMailbox’s bind (or add in the case of aBroadcastMailbox) arguments carefully.

Exceptions in info.net. Four exceptions are included with info.net: InvalidMessageException,MailDaemonException, TimeoutException, and UnknownMessageException. Please see theJavadocs for more information about these.

Remote class loading. Make certain that what you push on the wire is what you expect toget out. We recently witnessed weird behavior with the djinns using info.net. DateServer

was importing info.util.Date but TimeResponse was importing java.util.Date. So, theinterfaces were the same, and the compiler thought everything was fine, but when it came topushing the class over the wire and unmarshalling it things went poorly because info.net loadedup java.util.Date and tried to unmarshall a info.util.Date. As a result, the communicationlayer sent DenyMessages because info.net claimed that the receiving side could not parse themessage.

Deleting mailboxes. Make sure the Java program is finished with a mailbox before deletingit, especially taking care that the program has extracted all of the messages from that mailbox.

Chapter 4

Creating Djinns

This chapter discusses the process of creating djinns, their behavior, and their capabilities.

4.1 Using the info.djinn Package

To make a djinn, create a normal (public) class that extends the info.djinn.Djinn class. Don’tforget to “import” the proper classes in your code, usually a import info.djinn.* will suffice.The best way to write a djinn is to copy another one. A good djinn to copy that is part of the set ofdemonstration djinns provided with the II is the Server djinn info.demo.server.ServerDjinn.

info.djinn.Djinn is an base class that implements the methods defined in the Summonable

interface. Most of these implementations are empty and provide a djinn without much function-ality. You, as the djinn author, are responsible for implementing several of the methods of theSummonable interface: initDjinn, djinnMain, freeze, thaw, and setTrueName. We’ll look ateach of these methods in turn, but first we’ll discuss the interfaces that your djinn must support.

4.1.1 Your Djinn’s Types

The base djinn class info.djinn.Djinn implements two interfaces: java.lang.Runnable andinfo.djinn.Summonable. While info djinn.Djinn provides default implementations of all themethods of these interfaces, it is likely that you will want to override several of them for yourown djinn.

If you wish to create a djinn that is an applet, you should use the base class info.djinn.DjinnAppletinstead. Take a look at its javadoc documentation and the example applet in the info.demo.appletpackage, as discussed in section 6.12. Remember that applets can only connect back to the hostfrom which they were loaded!

The info.djinn.DjinnApplet base class has all the same methods as info.djinn.Djinn,so it is very easy to turn a “normal” djinn into an applet djinn. While applet djinns cannot berun from the command line (they expect to be in a browser or appletviewer, after all!), it won’tcrash them spectacularly or anything. Likewise, if you try to summon an applet djinn in a DjinnMaster, it will class load, be instantiated, etc., but nothing will happen beyond that.

47

48 CHAPTER 4. CREATING DJINNS

This behavior (running a djinn applet from the command line and inside of a djinn master) isdue to the constraint that we cannot tell, programmatically, if the object has been instantiatedinside of a browser or not. The applet framework just doesn’t give us this capability because itwas not in the original design of the java.applet package. Once we are provided with such amechanism, the code to support djinn applets running as normal djinns is already written.

We quickly discuss what these interfaces are all about and highlight which methods are ofinterest to a djinn author.

Summonable. The Summonable interface exists so that we can provide an abstract interfaceto our notion of a generic distributed object. The info.djinn.Djinn base class is only oneinstance of such a distributed object. For instance, we might wish to provide a specific base classfor dynamically migrating objects, and such an object would implement both the Summonable

interface and, hypothetically, a new Migratable interface.

Runnable. According to Java pioneers Arnold and Gosling, “A Runnable interface abstractsthe concept of something that will execute code while it is active.” Since our djinns run codewhile they are active, they implement the Runnable interface.

More precisely, a djinn must implement Runnable so that, when the djinn is instantiated anda Thread for that djinn is created, that Thread needs to call a specific method to get the wholeball of wax rolling. The most obvious mechanism for doing this is the Runnable interface.

The other reason that info.djinn.Djinn implements Runnable is for consistency acrossinstantiation mechanisms. Currently, the II supports running djinns as threads within the DjinnMaster. In previous releases, we supported the option of running a djinn as a separate process.While this capability still does exist in the code, and is documented briefly in chapter 5, we havecurrently turned off this option because of incompatibilities in various releases of Java.

Moving right along, we now look at what you need to do as a djinn author in creating yourown djinns. When implementing a djinn, the first thing you do is the same first thing you dowhen you have a child: you name it.

4.2 Naming Djinns

There are two kinds of “pointers” or “names” for djinns. The first one is immutable and iscalled the DjinnTrueName. This pointer is a reference to the djinn that will never change. TheDjinnTrueName contains a set of information that is fixed for a given release of a djinn. Thisinformation includes who wrote the djinn, who supports the djinn, and when the djinn wasreleased.

Note that the DjinnTrueName is similar to the GUID or CLSID from DCE and COM, in thatthe name is unique. In addition, the DjinnTrueName has semantic value to the runtime systemand to a human being. That is, a DjinnTrueName can be printed out and is understandable tothe average user.

4.3. DJINN INITIALIZATION 49

The other type of “pointer” is the DjinnName. A DjinnName is a pointer to a specific instan-tiation of a djinn and is globally unique. Djinn instantiation (summoning) and remote methodinvocation (service requests) are accomplished through the use of a DjinnName object.

For example, let’s say your djinn’s class is called MyDjinn. Also, let’s assume that your nameis Scott McNealy and you work for Sun Microsystems as a lowly engineer, then you might changethe setTrueName method of the example ServerDjinn in the following manner:

protected void setTrueName ()

{

djinnTrueName =

new DjinnTrueName ("Sun Microsystems, Inc.",

"Scott McNealy",

"[email protected]",

1, 0, "final", "$Date: 1998/01/23 23:06:49 $",

"My First Djinn",

"http://www.sun.com/");

}

Glancing at the above DjinnTrueName, one can quickly discover: which organization is re-sponsible for the djinn, who wrote it, what the contact email address is for the djinn, whatversion and release the djinn is in, when the djinn was release, what the djinn’s product nameis, and what the web address associated with the djinn or its originator.

When a new version of a djinn is released, it must have a new DjinnTrueName. Most often,this is accomplished simply through an update to its version, date, and name fields.

Now, you have given your djinn its DjinnTrueName. You might ask, “How do I give mydjinn its DjinnName?”. The answer is, you don’t. Just after a djinn is instantiated, but beforeany of its methods are called, the djinn “names itself”. It does this by discovering what itsDjinnTrueName is, then it creates its own DjinnName, filling in all of its fields appropriately forthis particular instance of the djinn.

We will be providing services to support finding, querying, and summoning djinns with vary-ing degrees of information. Perhaps you only know who wrote the djinn and the month in which itwas released, perhaps you only know that it is a Calender-like djinn owned by your boss, perhapsyou know the full DjinnTrueName but nothing else. Our searching, querying, and summoninginterfaces will be extensible enough capture and support all of these scenarios and more.

Now you have named your djinn. The next step is to set up your djinn’s distributed con-structor: the initDjinn method.

4.3 Djinn Initialization

The very first method that is called in your djinn is the initDjinn method. This happens justafter the djinn is instantiated and named. Your djinn’s initDjinn method can be viewed as amethod akin to a distributed constructor. The initDjinn method has the following signature:

void initDjinn (String [] args,

OutboxAssociationTable outboxAssociationTable,

boolean forwarded)


Normally, one uses the initDjinn method to create your djinn’s mailboxes, initialize instancevariables, and data structures.

When a djinn is summoned, an arbitrary number of parameters can be passed to the newdjinn. These parameters are passed to the summoned djinn in the String array args.

Likewise, when a djinn is summoned, the summoner can pass an object of typeOutboxAssociationTable. This table can be used to describe how the outboxes of the summoneddjinn should be “hooked-up” automatically after the djinn is instantiated. The infrastructureautomatically takes care of the creation and binding of the outboxes specified in a non-nullOutboxAssociationTable. See section 4.3.1 for more information about outbox associationtables.

Finally, both your initDjinn and djinnMain methods have a boolean parameter calledforwarded. We will discuss this flag in section 4.11. In short, if this flag is set to true thenyou know that your djinn is not the first instance running on a given server, but is instead aninstance that was spawned in response to another (beyond the first) request for an object of itstype.

As you will note, these parameters are passed to both the initDjinn and djinnMain methods,since the djinn might have need of them during, and possibly after, instantiation and initializa-tion.

Now your djinn is named and has initialization code. The next (and most important) step isto write the real “guts” of your djinn.

4.3.1 Outbox Association Tables

An outbox association table (class info.djinn.OutboxAssociationTable) is sent to a djinn atsummoning. It contains a hashtable associating keys (of class java.util.String) with lists ofinfo.net.Place objects and outboxes bound to those places.

When a djinn is summoned with a non-null outbox association table, its Lamp (see section 4.6)instantiates an outbox for each outbox association in the table, and binds each outbox to theplaces with which it is associated. For each outbox association which contains only one Place,an outgoing mailbox of type info.net.Sendbox is created; for each outbox association whichcontains more than one Place, an outgoing mailbox of type info.net.Broadcastbox is created.

The result of this is that a djinn summoned with a non-null outbox association table doesnot need to create and bind mailboxes by itself, except for any mailboxes it needs over andabove those specified in the table. It can call getOutbox on its outbox association table to findthe outbox associated with a specific key, and then use that outbox without needing to bind itmanually.

As an example of this, assume that a djinn receives an outbox association table containingtwo entries - one of them associates the key “acknowledge” with two places, “a.com 9876 ackbox”and “b.com 9876 ackbox”, and the other associates the key “hello” with one place, “c.com 9876hellobox”. The initDjinn method of this djinn might look like the following:

public void initDjinn(String [] argv,

OutboxAssociationTable outboxAssociationTable,

4.4. DJINN CODE 51

boolean forwarded)

{

myAckOutbox = outboxAssociationTable.getOutbox

(‘‘acknowledge’’, mailDaemon);

myHelloOutbox = outboxAssociationTable.getOutbox

(‘‘hello’’, mailDaemon);

}

This would then allow the djinn to use myAckOutbox and myHelloOutbox, which have alreadybeen bound to their respective destinations.

For more information on how to construct and use outbox association tables, see the APIdocumentation for info.djinn.OutboxAssociationTable.

4.4 Djinn Code

The central “main” method that is called to set your whole djinn in motion is the djinnMain

method. This method has the same signature, and is passed the exact same arguments, asinitDjinn.

When your djinnMain is initially called, you have a single thread of execution with whichto operate. If you have the need for additional threads, you are free to create them within yourdjinnMain, or its sub-methods, at will. You djinn will remain “live” and active for as long asyou have threads running. Once all of your threads are shut down and you return from thedjinnMain method, the II will take that action as a signal the your djinn can now go to persistentstore and be garbage collected.

We’ll look at a very simple djinnMain here, since we’ll be covering a more complex examplelater in this chapter. For example, your MyDjinn djinn might just want to print out a message.If this were the case, its djinnMain might look similar to the following:

public void djinnMain (String [] args,

OutboxAssocationTable outboxAssociationTable,

boolean forwarded)

{

System.err.println ("\n\n Hello, World! \n\n");

}

4.5 Adding Persistence

The freeze and thaw methods can be defined by the djinn to save/load persistent state. Theparameter to both methods is a DataStream, so reading and writing information to that streamis a snap.

You can think of the freeze and thaw methods as analogies to the writeData and readData

methods of the info.net.Message class. In the writing method you need to write data tothe stream in a an orderly manner that you define. In the reading method you need to readthat data back out of the stream and instantiate the appropriate objects with that data. Asimple example of djinn persistence can be found in the Persistent demonstration djinn. A much


more complicated examples of a persistent djinn is the Calendar application provided in theinfo.demo.calendar package.

4.6 Your Lamp, Your Friend

Every djinn has a corresponding object which actually does the job of calling its initDjinn,djinnMain, thaw and freeze methods with the proper parameters at appropriate times. Inkeeping with the metaphor of djinns, we call this object a lamp.

When a djinn is instantiated for the first time, either by direct invocation on the commandline or indirectly by a Djinn Master, its lamp (class info.djinn.Lamp) is created first. The lamp,in which the djinn will “live” while running, then creates an initial djinn thread and bootstrapsthe djinn. At every subsequent summons (assuming that the djinn in question is a server djinn),the lamp creates a new djinn thread. When all the djinn threads have stopped, meaning thatthe djinn is no longer running, the lamp saves the djinn’s persistent state and shuts down in anorderly fashion.

In addition to calling the initDjinn, djinnMain, thaw and freeze methods, a djinn’s lampis also responsible for handling requests from the djinn for communications (such as summons,dispells, and services) with all other djinns in the outside world, and for handling incomingrequests from other djinns in an appropriate fashion.

4.7 Summoning and Dispelling Djinns

4.7.1 Your Lamp Object

As mentioned previously, every running djinn has an object of class info.djinn.Lamp. A refer-ence to this object is stored as an instance variable, lamp, in the Djinn class. This means thata running djinn can access methods of its own lamp by calling lamp.*, where * is the name ofthe desired method.

4.7.2 The lamp.summon Method

When a djinn needs to summon another djinn, it calls lamp.summon. lamp.summon returns aDjinnName corresponding to the summoned djinn, and has the following syntax:

public DjinnName summon (DjinnName sourceDjinnName,

DjinnName targetDjinnName,

OutboxAssocationTable outboxAssociationTable,

String [] args,

long timeout)

throws SummonException

The arguments passed to lamp.summon are as follows: sourceDjinnName is the name ofthe djinn doing the summoning (so a djinn calling lamp.summon would use its own djinnName

instance variable for this field); targetDjinnName is the name of the djinn being summoned,

4.7. SUMMONING AND DISPELLING DJINNS 53

which can be left incomplete; outboxAssociationTable is the outbox association table (seesection 4.3.1) to be used for the summoned djinn; args is an array of strings, to be passed asarguments to the summoned djinn; and timeout is the number of milliseconds to wait for aresponse from the summoned djinn — if omitted, a default timeout will be used.

As an example, assume that you want to summon a CalendarDjinn belonging to user ralph,passing it no arguments and no outbox association table, using a Djinn Master running on port9876 of host ralph.com, and waiting for a timeout period of 10 seconds. You would then usethe following code:

DjinnName ralphCalendar = null;

try

{

ralphCalendar =

lamp.summon(djinnName,

new DjinnName(‘‘ralph’’,

new Place(‘‘ralph.com 9876 II_DJINNMASTER_IN’’),

‘‘CalendarDjinn’’),

null,

null,

10000);

}

catch (SummonException e)

{

System.err.println(‘‘Oops, something went wrong with the summon.’’);

// appropriate error handling code here

}

Note that lamp.summon is a synchronous call — it will not return until either the summonis successfully completed or a SummonException is raised. If the timeout period expires, aSummonException is raised indicating that the summon timed out.

4.7.3 The lamp.dispell Method

When a djinn is done working with a remote djinn which it has summoned, it should calllamp.dispell on the remote djinn. This lets the remote djinn know that it is no longer neededby the dispelling djinn, so it can perform whatever cleanup tasks are necessary to finalize itsinteraction with the dispelling djinn. The syntax of lamp.dispell is as follows:

public void dispell (DjinnName djinnName,

long timeout)

throws DispellException

The arguments passed to lamp.dispell are the full DjinnName of the djinn to dispell, andthe time in milliseconds to wait for a response from the dispelled djinn. If the timeout is omitted,a default timeout will be used.

For example, if you want to dispell the CalendarDjinn you summoned in the previous example,waiting for a timeout period of 10 seconds, you can use the following code:

try

{


lamp.dispell(ralphCalendar, 10000);

}

catch (DispellException e)

{

System.err.println(‘‘Oops, something went wrong with the dispell.’’);


}

Like lamp.summon, lamp.dispell is a synchronous call and will not return until either thedispell is successfully completed (that is, the method returns and the djinn is not necessarily shutdown) or a DispellException is raised. If the timeout period expires, a DispellException israised indicating that the dispell timed out.

4.8 On Being Dispelled

When a djinn calls lamp.dispell on the DjinnName of a remote djinn it had previously sum-moned, this does not automatically force the remote djinn to clean up and shut down. Instead,it causes the dispell method of the remote djinn to be called.

Note that, in general, a djinn should expect to receive dispell messages from one of twodifferent sources; either from the djinn that started it (the parent) or from the Djinn Master.Of course, one can receive a dispell message from any djinn. If a dispell request is received by adjinn, its dispell method is always called. It is up to the djinn to determine whether the dispellmessages is a valid message.

The validity of a dispell message varies from djinn to djinn. Here are some typical examplesof definitions of dispell message validity:

• The message comes from the djinn that originally summoned this particular djinn (that is,the same djinn as is referenced in the DjinnThread.getParentDjinnName method. To get areference to your djinn’s parent’s DjinnName, use the info.djinn.Djinn.getParentName

method.

• The message comes from the Djinn Master inside of which the current djinn is running.When such a message arrives, you must at least checkpoint, if not shut down completelybecause your Djinn Master is about to shut down!

• The message comes from a djinn with which this djinn is or was involved, but not the djinnthat originally summoned it. In this situation, often times the dispell message just means“I am done using/interacting with you,” not necessarily “shut down completely.”

• The message comes from some other random djinn with which you are not currently in-volved. Usually your djinn should just ignore these messages.

One useful application for the dispell facility is the implementation of a distributed final-ization algorithm, such that a djinn is explicitly notified when each of the other djinns whichhave summoned it are finished using it and can shut down in an orderly fashion when nobodyneeds it for active computations.

4.9. DJINN SERVICES 55

4.8.1 Your dispell Method

The class info.djinn.Djinn has a dispell method with the following syntax:

public void dispell(DjinnName djinnName)

throws DispellException

This method is called by your lamp when a remote djinn dispells you. djinnName is the djinnname of the dispelling djinn. Depending on the way you have overridden Djinn.dispell, itcan do anything it likes inside its dispell method, ranging from checking the dispelling djinn’sDjinnName against a list of djinns with which it has currently running interactions to ignoringthe dispell request entirely. If this method raises a DispellException, the exception will becommunicated by the infrastructure to the djinn which originally made the dispell call.

Because lamp.dispell will not return to its caller until your dispell method returns, thetimeout period expires, or a DispellException is thrown, it is generally best not to do toomuch processing within your dispell method. If there is a lot of cleanup to do on a dispell,you should spawn a new thread or set a flag that can be used by an existing thread, rather thandoing the cleanup immediately.

4.9 Djinn Services

4.9.1 The lamp.service Method

When a djinn needs to request a service from another djinn, it calls lamp.service. lamp.servicereturns a ServiceResponse containing the result of the service request, and has the followingsyntax:

public ServiceResponse service(ServiceRequest serviceRequest,

long timeout)

throws ServiceException

serviceRequest is an object of class info.djinn.ServiceRequest (or a subclass thereof),containing the DjinnName for the requesting djinn, the DjinnName for the djinn from whichthe service is being requested, and other information specific to the type of service being re-quested (if a subclass of ServiceRequest is used). serviceResponse is an object of classinfo.djinn.ServiceResponse (or a subclass thereof), containing the DjinnName for the re-sponding djinn, the DjinnName of the djinn which originally made the service request, the originalServiceRequest object which was sent by the requesting djinn, and other information specificto the type of service being requested (if a subclass of ServiceResponse is being used).

If, for example, you want to send a generic service request to the CalendarDjinn you’ve beenusing in the previous examples, you can use the following code:

ServiceRequest theRequest =

new ServiceRequest(djinnName, ralphCalendar);

ServiceResponse theResponse = null;


try

{

theResponse = lamp.service(theRequest);

}

catch (ServiceException e)

{

System.err.println(‘‘Oops, there was a problem with the service call.’’);


}

Like lamp.summon and lamp.dispell, lamp.service is a synchronous call and will not returnuntil either the service request is successfully completed or a ServiceException is raised. Unlikelamp.summon and lamp.dispell, however, there is no timeout period for a lamp.service call.

4.9.2 Your service Method

The class info.djinn.Djinn has a service method with the following syntax:

public ServiceResponse service(ServiceRequest serviceRequest)

throws ServiceException

This method is called by your lamp when a remote djinn requests a service from you.serviceRequest is the service request sent by the requesting djinn. Depending on the way youhave overridden info.Djinn.service, different service requests (that is, different subclasses ofinfo.djinn.ServiceRequest) may be dealt with in different ways. In any case, an object of classServiceResponse (or a subclass thereof) should be returned once whatever processing necessaryto handle the ServiceRequest has been completed. If this method raises a ServiceException,the exception will be communicated by the infrastructure to the djinn which originally made theservice call.

When the lamp receives a ServiceRequest from a remote djinn, it spawns a new threadto handle the interaction with your djinn’s service method and to send the ServiceResponse

back to the requesting djinn. Because of this, your djinn’s service method can be called bymultiple threads at the same time, so it must be written in a thread-safe manner. If your djinn’sservice method is not designed to be reentrant, you should add the synchronized keyword tothe method declaration when you override info.Djinn.service.

4.10 Other Methods of Importance

4.10.1 The main Method

The main method of a djinn is primarily used to bootstrap the djinn from the command line.While it is certainly possible to use the main method for other purposes, such as to provide aninterface for configuring a djinn, such uses tend to be unnecessary since they can be implementedjust as easily in other ways (using facilities such as services and command line arguments, whichare available both locally and remotely).

An example main method which bootstraps a djinn is the following (in this instance, thedjinn being bootstrapped is of class ExampleDjinn):

4.11. DJINN MODES 57

public static void main(String [] argv)

{

ExampleDjinn djinn = new ExampleDjinn(argv);

Thread djinnThread =

new Thread(djinn, ‘‘Initial ExampleDjinn Thread’’);

djinnThread.start();

Thread.currentThread().yield();

}

4.10.2 The run Method

The run method of a djinn handles the instantiation of the djinn’s Lamp and MailDaemon objects,and starts the djinn running. Normal djinns should never need to override the run method;however, special djinns (such as info.master.DjinnMaster) may need to do so for variousreasons. In general, unless you have an extremely good reason to do so, do not override the run

method.

4.11 Djinn Modes

Djinns can be instantiated by the Djinn Master in one of three modes, as discussed in section 2.6:server per request, persistent server per session, and mutually exclusive server per session. Modesof djinn operation are specified by tags in the Djinn Master’s dmrc configuration file. For moreinformation on these djinn mode tags, see section 5.3.

4.12 Djinn Command-line Flags

The djinn framework provides a set of default command line flags that you can pass to yourdjinns. These flags are used by the II to set the proper values of specific variables for each andevery djinn. You, as the djinn developer, can also use these flags to set the values of specificvariables. In particular, the -iin, -iip, iidebug, and various mode switches are quite useful.

The djinn command-line flags available in the II 1.0 are the following:

• -iiu <username>) - this flag is used to set the InstanceOwner of a djinn. Normally, a djinn’sowner is set to the owner of the Java VM, as reported by the “user.name” property of therun-time. Of course, many Java VMs do not report a proper username, and several popularoperating systems have no notion of a user, therefore this flag is available to override thedefault behavior.

• -iin <name> - this flag is used to set the InstanceName of a djinn. The parameter thatfollows the -iin flag should be a string. If you wish to give a djinn a name that includesspecial characters or white space, make sure to properly delimit your parameter with quotesand/or escape your special characters.


• -iip <port> - this flag is used to set the port on which a djinn’s MailDaemon is to run. Ifa port is unavailable an exception is thrown and the djinn exits. Don’t forget that portsbelow 1024 are reserved for system use.

• -iim <host port> - this flag is used to set the location of the Djinn Master that is responsiblefor this djinn. The parameters that follow the -iim are the hostname and port number ofthe djinn master.

• -iid <date> - this flag is used to set the SummoningDate of a djinn. The parameterfollowing the -iid flag should be a long integer specifying the UTC date (as returned byjava.util.Date.getTime().

• -iio <OutboxAssociationTable> - this flag is used to pass a set of outbox associations to adjinn, in the format generated by info.djinn.OutboxAssociationTable.toArgs().

• -iidebug - this flag enables debugging output. All output sent to the System.out and Sys-tem.err streams will be printed out on the console. Our debugging class, info.util.Debugprovides a standard interface for sending typed debug messages. Please see the javadocdocumentation on this class for more information.

• -iiinstance - this flag informs the djinn that it is to run in INSTANCE mode; see section 5.3for more information on djinn run modes.

• -iimuxl - this flag informs the djinn that it is to run in MUXL mode; see section 5.3 for moreinformation on djinn run modes.

• -iiserver - this flag informs the djinn that it is to run in SERVER mode; see section 5.3 formore information on djinn run modes.

• -iinoawt - this flag tells the infrastructure not to start the AWT (the infrastructure does thisto work around the fact that the virtual machine’s AWT threads, once started, never die);it should be used when running on systems with no graphics capability, or when runningon systems where starting the AWT causes the virtual machine to freeze (this happensoccasionally on Windows NT with JavaSoft JDK 1.1.3 and earlier).

Chapter 5

The Djinn Master

5.1 What is a Djinn Master?

The Djinn Master is a kind of a personal mini-orb that is part of your Infosphere. The DjinnMaster is responsible for the instantiation of, and the initial communication to, persistent djinnsin a distributed application or session. The Djinn Master maintains a table of current djinnsrunning; if a message comes in for a djinn that is not currently running (or does not currentlyexist), the appropriate djinn is thawed (or initiated) and executed, and the message is forwardedto the djinn.

The Djinn Master needs to have some knowledge of your system, as discussed in chapter 1.You summarize this information in a file called master.res. The file is found in your personalii data directory. You are responsible for modifying the master.res file so that your DjinnMaster can find various tools and data on your system.

The Djinn Master keeps track of all the djinns that are part of your Infosphere in a file calleddmrc that is found in your personal ii data directory. This file can be though of as an indexof all the persistence communicating objects to which you have access. Such an index can alsobe viewed as an index into an implementation repository, if you are familiar with the CORBAworld. We are investigating solutions for providing such a repository (both implementation andinterface) for larger collections of djinns – across organizations and even across the Internet.

When a new djinn is requested (summoned), the Djinn Master will either:

• Create a new djinn, passing the supplied arguments.

• Forward the request to an already running djinn.

• Report an error (for example, the requested djinn not installed).

5.2 Configuring Your Djinn Master

The Djinn Master has to be configured for your system and for your environment. This configu-ration is performed at the Djinn Master level in a file called master.res, and at the individual

59

60 CHAPTER 5. THE DJINN MASTER

level in a file called dmrc. This section will discuss how to configure your Djinn Master for yoursystem and for yourself.

5.2.1 The master.res File

The master.res file is fundamentally a set of environmental variables that the Djinn Masteruses in configuring itself. Since Java 1.0 does not support environmental variables, we had toput this information into a configuration file. The structure of this file is compatible with futuresupport for environmental variables or similar configuration structures. The default master.resconfiguration file is the following:

#default: CLASSPATH "../source/"

#default: DJINN_CLASSPATH "../source/"

#default: DJINN_FLAGS ""

#default: DJINN_IMPLEMENTATION_NAME "unnamed"

#default: DJINN_LOCAL_NAME "unnamed"

#default: EXEC_FLAG "true"

#default: PATH "<java.home>/bin"

#default: ROOT_MASTER_FLAG "false"

#default: DJINN_INIT_FLAG "THREAD" (THREAD, PROCESS)

#default: DJINN_RUN_FLAG "INSTANCE" (INSTANCE, SERVER, MUXL)

#default: USER_PATH "user.home"

#

CLASSPATH=/ufs/comp/kiniry/info/source/:.

#

PATH=/usr/local/jdk1.1.5/bin;/usr/local/jdk1.0.2/bin;/usr/local/bin

The first thing to note is that lines that begin with the hash symbol (“#”) are ignored bythe Djinn Master (they are comments). Each entry in the default configuration file displays thedefault setting for the Djinn Master. If you do not specify any non-comment fields, or you do notsupply a master.res file, then the Djinn Master will start with the default settings and informyou of such.

There are eleven variables that can be set in the master.res file to set the default behavior ofthe Djinn Master. Note that the Djinn Master, in truth, will run without any of these variablesset at all; the default settings are sufficient for the Djinn Master to run under most circumstances.A summary of the variables follows:

• CLASSPATH is a legitimate classpath from which a classloader can load the info class tree(for example, a zip file, tar file, or jar file).

• DJINN CLASSPATH is a legitimate default classpath from which a classloader can load thedjinn’s related to this particular Djinn Master. This value is overridden by the classpaththat is set on a per-djinn basis in the dmrc file.

• DJINN FLAGS is the amalgamation of the various flags that can be set for djinns. That is, ifyour djinns have a default value of INSTANCE for the DJINN RUN MODE flag, and of THREADfor DJINN INIT MODE, then your default DJINN FLAGS value should be INSTANCE,THREAD.Actually, this value is only used for debugging purposes, so you need not set it at all.

5.2. CONFIGURING YOUR DJINN MASTER 61

• DJINN IMPLEMENTATION NAME is the default name of the class or executable that “is” thedjinn.

• DJINN LOCAL NAME is the default local name of the djinn which not used except in lookupduring summons and in naming threads.

• EXEC FLAG is a flag indicating whether or not the Djinn Master is permitted to call theRuntime.exec method.

• PATH is the local path that includes the java runtime executable. For example, if your JDKis installed in the path /usr/local/java, this element would be /usr/local/java/bin/.

• ROOT MASTER FLAG is a flag indicating whether or not the Djinn Master is running asroot/privileged user.

• DJINN INIT FLAG is a flag indicating which mode the djinn is to be started in. The currentrecognized choices are PROCESS and THREAD, though we currently have the PROCESSoption turned off.

• DJINN RUN FLAG is a flag indicating in which mode the djinn is to run by default. Thecurrent choices are INSTANCE, SERVER, and MUXL.

• USER PATH is the path to the root of the Djinn Master’s user-specific store of state files.If this variable is set, the Djinn Master will look in this path for the dmrc files for all theusers that are under this Djinn Master’s jurisdiction.

As might be predicted from the structure of this resource file, we wished to support initialconfiguration of the Djinn Master through environment variables. The problem with this ideais that, as of JDK 1.0.2, Java does not support access to such variables (though the API isthere, the methods are empty). If such support existed and worked reliably on a large numberof platforms, it will remove the need for master.res file entirely.

5.2.2 The dmrc File - General Discussion

Each user has a configuration file for his or her Djinn Master(s). Through it is often the casethat there is a one-to-one relationship between Djinn Masters and users, this is not always thecase. Meaning, it is possible to run a Djinn Master which is responsible for a collection of users.

The configuration file for the Djinn Master is called dmrc as is located in your personal ii data

directory. If you have not yet installed the package and wish to do so, please see chapter 1 formore information.

Note: the Djinn Master searches for your dmrc file in a specific manner: first the DjinnMaster checks to see whether the USER PATH variable was set in its master.res configurationfile. If it was, then it assumes that a user user name’s dmrc file is assumed to be in the pathUSER PATH/user name/dmrc.


For example, if we are summoning the djinn HairBallDjinn that is owned by the userbill the cat, and the Djinn Master that we are contacting has a USER PATH of /usr/local/djinns,then the full path at which the Djinn Master will expect to find the dmrc file is/usr/local/djinns/bill the cat/dmrc, in which it will look for an entry called HairBallDjinn.(End of Remark.)

To continue, the dmrc file details each and every djinn that you wish to run in a precisemanner. First, we’ll look over the format of this file so that you can modify the entries that weprovide by default and add entries of your own.

5.2.3 The dmrc File - Specifics

Each djinn that you wish for your Djinn Master to be able to run has an entry in the dmrc

file. Our example dmrc file separates each entry by a blank link, but this is not necessary forcorrectness. Lines whose first character is a “#” are treated as comments and ignored. Eachnon-comment entry in the dmrc file has four fields, separated by white space. The fields arecalled DjinnInstanceName, DjinnClass, DjinnRemoteClasspath, and DjinnFlags, respectively.

1. DjinnInstanceName, is the djinn’s local name. This is the name by which you, the user,refer to the djinn. Likewise, this is the name by which other djinns or users summon yourdjinn.

One would like to be able to refer to a component in your Infosphere without havingto describe that component’s application name, version, etc. For example, I should beable to say “Hey Bill, have your secretary object contact my secretary object and we’lldo lunch.” In this example, your secretary object might be Microsoft Secretary version2.11 for Windows NT and Bill’s secretary object might be Apple Administrative Assistant(triple-A) version 3.0 for Rhapsody.

Basically, your object doesn’t need to know anything about the kind, version, or imple-mentation of any object that it is with which it is interacting; it only need know the remoteobject’s local name and be assured that the remote object conforms to the proper interfaceand behavior.

2. DjinnClass is the base class of the djinn that need be instantiated. The classname that isused in this field must be a fully specified (complete) Java classname, as you would typefrom a command line. This class must implement the Summonable interface and, currently,subclass info.djinn.Djinn.

3. DjinnRemoteClasspath is a list of URLs from which the djinn’s classes can be loaded. URLsshould be bracketed by pointy brackets (< and >) and comma separated. URLs includedin this list can include any legal URL accepted by a standard web browser. We have testedfile:, http:, and ftp: URLs. See section 5.4 for example remote classpaths.

4. The fourth field is a sequence of comma-separated flags specifying how the Djinn Masterinteracts with the running djinn. The flags should have no whitespace between them.See the next section for details on valid values for these flags and their meaning.

5.3. DJINN MASTER MODE FLAGS 63

5.3 Djinn Master Mode Flags

The Djinn Master in II 1.0 recognizes five different mode flags for djinns.A djinn can only have one of the instance, server, and muxl flags set; they are mutually

exclusive flags. Likewise, the thread and process are mutually exclusive. The instance and threadflags are the default modes of djinn instantiation in II 1.0.

• instance indicates that each and every time the djinn is summoned it is a separate, new,unique instance.

• server indicates that each and every time the djinn is summoned the same instance isinvoked.

• muxl indicates that each and every time the djinn is summoned, the same instance isinvoked but only if no other instance of the djinn is currently running.

• thread - indicates that the djinn is to run as a thread within the Djinn Master’s Java VirtualMachine.

• process - indicates that the djinn is to run as a separate and distinct process; a new JavaVirtual Machine devoted exclusively to running this djinn.

Thus, in general, if a djinn is an “instance djinn”, each summons will result in a new instanceof the object, much like a remote “new” operation. If the djinn is a “server djinn”, the very firstsummons will create a new djinn, but each following summons will return a reference to thatsame djinn. Finally, if the djinn is a “muxl djinn”, its behavior is the same as the “instancedjinn” except that only a single instance of it can exist at any one time, from the perspective ofthe Djinn Master.

A more detailed discussion of summoning modes can be found in section 5.5.1.

5.4 Some Example dmrc Entries

In this section we look at several dmrc entries, discussing the relevance of each part of the entryand how changes to the entry will affect djinn behavior. All of the following examples are foundin the default dmrc file included with the II.

5.4.1 Hello World

The HelloWorld djinn, briefly discussed in section 4.4, has the following dmrc entry:

HelloWorldThreadFile info.demo.helloworld.HelloWorld \

<file:/ufs/info/usr/kiniry/djinns/> \

instance,thread


The first field is the local name of this djinn: HelloWorldThreadFile. We gave the djinnthis wordy name so as to help us remember what the behavior of the djinn was supposed to be;that is, this djinn has the instance and thread flags set and is to have its classes loaded from thelocal filesystem.

The second field is the full class name for the djinn. The HelloWorld class is the object thatinherits from info.djinn.Djinn, thus it is the entry here. Note the use of the full package-izedname.

The third field is a reasonable class path from which the djinn can load. In this case that classpath is a “file:” URL that refers to the local filesystem directory “/ufs/info/usr/kiniry/djinns/ ”.Thus, one expects to see the class file “HelloWorld.class” in the directory“/ufs/info/usr/kiniry/djinns/info/demo/helloworld/ ”.

The final field is a set of flags that indicate to the Djinn Master the behavior that this djinnexhibits and its expected runtime environment. Thus, in this example, the HelloWorld djinnexpects to run as a thread inside of the Djinn Master and depends on the fact that each andevery invocation of it (summon) will result in a new and distinct instance of the class with newand distinct persistent state.

5.4.2 Webster Server

For the WebsterServer djinn, we provide a multi-part class path from which the djinn can beloaded. Also, we use a different flag (the “server” flag) to indicate that the djinns acts more likethe traditional object server. Here is the entry:

WebsterServer info.demo.dictionary.WebsterServer \

<http://www.cs.caltech.edu/~kiniry/djinns/,file:/ufs/info/usr/kiniry/djinns/> \

server,thread

The first (instance/local name), second (class name), and part of the fourth (the thread flag)fields should be completely familiar and need no explanation. What is new is the extended classpath field and the server flag in the fourth field.

This lengthy class path means the following: the WebsterServer and supporting classes canbe found via either or both the URLs listed in the entry. These URLs will be searched for remoteclasses in an arbitrary order, determined internally by the remote class loader.

What a “remote classloader dependency” is for the II classloader is precisely defined in theclass info.net.MultiURLClassLoader. In short, classes outside of what your Java runtimebelieves are “system classes” (as defined by ClassLoader.findSystemClass()) are considered“remote classloader dependencies” at this time.

The server flag found in the fourth field indicates that the WebsterServer djinn behaves inthe following manner. The first time (ever) that the WebsterServer is summoned it will beinstantiated and will have no state besides that which it defines itself in its code. Now, each andevery instance that is requested of the WebsterDjinn will return a reference to this same firstinstance. Programmatically, new summons will cause new threads of execution within the bodyof the WebsterDjinn to be instantiated. Thus, server djinns must be thread-safe in their entirety.

5.5. INVOKING OPERATIONS VIA THE DJINN MASTER 65

5.4.3 Mutual Exclusion

The TestMuxl djinn has the muxl flag set in its djinn modes field. Muxl stands for mutuallyexclusive, meaning that the djinn can only be accessed by a single djinn at any point in time.That is, if djinn A summoned the TestMuxl djinn, then djinn B tried to summon the TestMuxldjinn, djinn B would get an exception indicating that the TestMuxl djinn is currently unavailable.Only after djinn A dispells the TestMuxl djinn can djinn B summon it and send it messages.This is something of a busy-signal approach; we want to provide a queuing-access approach in alater version of the II.

TestMuxl info.demo.testsuite.ServerDjinn \

<file:/ufs/info/usr/kiniry/djinns/,ftp://ftp.cs.caltech.edu/djinns/> \

muxl,thread

For TestMuxl, we suggest that the Djinn Master classload from the local filesystem or fromthe FTP server ftp.cs.caltech.edu. This example shows that you can classload from manydifferent sources: the local filesystem, a web server, and even an ftp server. We do not yetsupport classloading from other web resources (for example, gopher servers and wais servers).

5.4.4 Persistent File

The PersistentFile djinn entry the use of file: URL classpaths on Windows 95 and NT ma-chines. Note the two different supported syntaxes for this type of URL on Windows.

PersistentFile info.demo.persistent.PersistentServer \

<file:///D|/Kiniry/info/source/,file:///C:/Kiniry/info/source/> \

server,thread

The leading browsers on the Windows platforms all support the use of the vertical bar (“|”)in place of the standard colon (“:”) following a drive letter in file URLs. So, as to not confusethe issue, we support the same convention in our file URLs in the dmrc file entries’ classpath.

Wrap Up. These four examples cover the whole range of djinns that are supported in thisrelease of the II. As we add more functionality to the II we will provide more examples of dmrcentries as appropriate.

5.5 Invoking Operations via the Djinn Master

The Djinn Master not only acts as an object server for djinns, but it is also an ORB for summon,dispell, and service messages. Meaning, if you send a Djinn Master a message of one of thesethree types, or their subtypes, that is destined for a djinn under its jurisdiction, (that is, runningwithin its address space or under its control), it will forward the message on to the appropriateinterface of that djinn.

This facility will be much more useful once we expand the DjinnName matching algorithmswithin the Djinn Master. Currently, the destination of a given message must be the full and


complete DjinnName of a djinn. We are working on providing a form of “weak lookup” which willpermit a sending djinn to deliver a message to a running instance with incomplete information.

This can be a convenience, particularly if you know that a particular djinn is running underthe control of a given Djinn Master, but you do not know the actual instance location of the djinn.Meaning, when a djinn sends a message to the Djinn Master for forwarding, it will only have tospecify some subset of the full DjinnName for delivery to take place. This functionality is directlyrelated to some of the services that we are working on for Djinn Masters (see section 5.6.3) formore information).

5.5.1 Summoning Djinns

When a summon request comes in to a Djinn Master, it must decide what to do with the message.The Djinn Master’s ORB-like capability comes into play when the summoned djinn is a “serverdjinn” and is currently running. In this case, the Djinn Master simply forwards the summonrequest to the running djinn. That djinn will automatically receive the message, process itcorrectly, and start up a new thread of execution within its context. All other summon requestsare not forwarded in any way, they are processed by the Djinn Master in the manner appropriate,given their destination, the current state of the Djinn Master, and the current state of the djinnsrunning within the Djinn Master’s jurisdiction.

5.5.2 Dispelling Djinns

The Djinn Master, on receiving a dispell request, first determines whether that message is boundfor itself; that is, it is a message destined for the Djinn Master requesting that it shut down.If it is not, the Djinn Master determines whether the message is bound for a djinn within itsjurisdiction. If this is true, it forwards the dispell message on to the djinn in question. If not, itsends back an exception to the dispeller.

5.5.3 Requesting Services

Finally, similar to the above discussions, the Djinn Master is capable of forwarding servicerequests on to running djinns within its scope. That is, if you send an object that inheritsfrom service request to a Djinn Master with a legitimate destination DjinnName, the DjinnMaster will determine if that destination djinn is running and, if so, will forward the message onunchanged to the destination djinn.

5.6 Invoking Operations on the Djinn Master

The Djinn Master is itself a djinn, thus it can be summoned and can accept service requests.Currently, no services are provided by the djinn master as part of the service infrastructure.

5.7. THE OUTPUT GENERATED BY THE DJINN MASTER 67

5.6.1 Summoning a Djinn Master

Since the Djinn Master is a djinn, it can be summoned via another Djinn Master. This issomething of a confusing and bizarre notion - quite self-referential and recursive. If you wish totry this out, look for the entry in the dmrc file that is of the following form:

MasterThread info.master.DjinnMaster \

<file:///D|/Kiniry/info/source/> \

server,thread

By summoning the “MasterThread” djinn you will, in fact, summon a Djinn Master inside ofthe Djinn Master that you are contacting. This new inner master will function just like you wouldnormally expect. Why anyone would wish to do this, we have no idea, but it is an interestingconcept and execution none-the-less.

5.6.2 Dispelling a Djinn Master

When a djinn master is to be shut down, it should be sent a dispell message, just like any otherdjinn. When a Djinn Master is dispelled, it needs to complete an orderly shut down of all thedjinns running within its address space. Currently, this is accomplished by sending every one ofthem (in series) a dispell message. After all djinns have been alerted that the Djinn Master isshutting down, it freezes itself and exits. See chapter 4, section 4.8 for more information on thesemantics of dispell messages.

5.6.3 Requesting Services from a Djinn Master

The Djinn Master provides no base services at this time. Feel free to subclass info.master.DjinnMasterand provide your own.

5.7 The Output Generated by the Djinn Master

A large amount of debugging output can be generated by the Djinn Master if debugging is turnedon (with the -iidebug flag) and it behaving correctly. Do not be concerned unless it prints astandard exception stack trace; if it does this, please send us a copy of the dump and a briefdescription of what you were doing as part of a bug report. You can re-route this dump to afile; remember all debugging output is sent to standard error. See the Appendix A for moreinformation on debugging djinns.

5.7.1 Use of the info.util.Debug Class

The info.util.Debug class is our central standard debugging facility for the II. Currently, thecode base is actually much larger than it needs be because we have debugging code scatteredthroughout. We are developing a Java pre-processor to handle this, and many other related


software engineering problems. See our web pages for more information on this, and othersimilar tools.

If you too would like to use our Debug class, please see the Javadocs on the info.util.Debugpackage in the documentation tree included with this release.

Chapter 6

Example Djinns

Before taking our examples for a test-run, you must install the package as described in section 1.6,Installing the Infospheres Infrastructure. For a brush-up, here is a quick review of the installincludes:

• Make sure that the Java runtime of your JDK is in your path.

• Make sure that your CLASSPATH includes our classes (that is, it should include the pathto the root of the source tree (./source/). Don’t forget that many Java run-times like atrailing colon on your CLASSPATH.

• For details on Djinn Master installation and setup, see chapter 5.

Do not forget to set your permissions correctly if you are on a X-Windows enabled system (viaxhost, xauth, or whatever) to allow remote applications to display remote application windowson your desktop! If you run your Djinn Master(s) on a machine/some machines other than theone which you are running your X server these example djinns will be instantiated on thoseremote hosts and they must have the authority to display their interfaces to you.

All examples are included in the ./source/info/demo/ directories. Each djinn has its ownpackage. We will be releasing a suite of more sophisticated demonstration djinns during theSpring.

You can either start djinns with the Initiator Djinn (not included in this release) or theSummoner Djinn. The Initiator Djinn gives you a visual interface to starting up djinns in anetwork environment. The Summoner gives you command-line or GUI control over summoning,dispelling, and sending service requests to djinns.

Note that nearly all djinns can be run with no parameters or the “-h” parameter an theywill display a help/usage message for you.

Since all objects in our system are djinns and we use Summoner for our examples, we discussthe Summoner Djinn first.

69

70 CHAPTER 6. EXAMPLE DJINNS

6.1 Summoner

The Summoner is a small tool that we use to interact with and test djinns. It provides acommand-line or GUI interface for invoking, dispelling, and querying djinns on local and remotesystems. The Summoner is in the package info.demo.summoner.

To run the Summoner with a GUI interface, run the script GUIsummoner.sh or GUIsummoner.batfor UNIX and Windows, respectively, found in the ii data directory of the package. To use theSummoner from the command line, use the script summoner.sh or summoner.bat, which is equiv-alent to the command“java info.demo.summoner.Summoner -iiserver <params>”.

The Summoner has a variety of command line parameters:

• -m master host port tells the Summoner which Djinn Master to contact to summon thedjinn. Recall that the default port of the Djinn Master (or any djinn for that matter) is9876. If you had specified that the Master run on a different port with the -iip djinn switchthen you must contact the Master at that location.

• -i instance host port tells the Summoner where the djinn instance that it is to interactwith is running.

• -d local djinn name tells the Summoner which djinn with which we wish to interact.Note that the parameter passed is the local djinn name, the name by which the DjinnMaster knows the djinn, which is equivalent to the name by which the user owning thedjinn refers to that djinn. For example, I might use the FooBarMailApp mail tool but I justcall it my Mail djinn in my dmrc, thus you should summon that djinn with a “-d Mail”switch. This local name is the first element in each and every entry in the dmrc file in yourii data directory.

• -u username tells the Summoner which user’s djinns we are interested in contacting.Meaning, we can summon djinns owned by any user that belongs to the Djinn Master weare contacting, so this switch specifies which user we are interested in.

• -D tells the Summoner to dispell the djinn specified after summoning it. Note that, todispell and running djinn you need the full DjinnName for that djinn. Since that nameis something too complex to be typed on a command line, you cannot arbitrarily dispellrunning djinns with the summoner.

• -S tells the Summoner to send a generic service request message to the djinn in question.

• -M indicates to the Summoner that it is interacting with a Djinn Master. This switch isused in the special case when you are dispelling a running Djinn Master from the commandline. See below for more information on the use of the -M switch.

• -g causes the Summoner to run with a GUI. The Summoner then ignores all command lineswitches relating to the djinn to summon.

6.1. SUMMONER 71

• -h prints out help for the Summoner.

• All other parameters are passed on to the summoned djinn.

An Example. Here is an example of the Summoner’s use:I wish to summon the HelloWorld example djinn. First, I need to run a Djinn Master on

some system. For this example I’m going to run my Djinn Master on the NetBSD systemlute.cs.caltech.edu. I started that Djinn Master by opening an Xterm on lute.cs.caltech.edu,changing directories to my ii data directory that is located in my home directory, and runningthe master.sh script located therein. If I want to see debugging output, I use the -iidebug

switch. If I were running on a Windows computer, I would be using a command prompt or DOSwindow and I would have run the master.bat instead.

Now, adjacent to the script that I just used to start my Djinn Master I see my personal dmrcfile. My dmrc file has the following line in it:



instance,thread

This entry means that the djinn that I call HelloWorldThreadFile is actually the classinfo.demo.helloworld.HelloWorld and can be loaded with the URL classpathfile:/ufs/info/usr/kiniry/djinns/. So, if I look in the directory /ufs/info/usr/kiniry/djinns/

on lute.cs.caltech.edu, I see the directory containing the source code for the II package, or atleast the directory hierarchy corresponding to, and including, the info.demo.helloworld package’sclasses. Or, to put it another way, if I were to use /ufs/info/usr/kiniry/djinns/ as a compo-nent in my CLASSPATH, and I were to run the command “java info.demo.helloworld.HelloWorld”from a command line, the HelloWorld djinn would run without any Djinn Master. We call suchDjinns “rogue djinns” - djinns without Masters.

Also, the entry includes two switches. The use of the thread switch tells the Djinn Masterto run this djinn as a thread group inside of its own Java run-time. Meaning, a new processwill not be started. The server switch tells the Djinn Master that this djinn is going to run as aserver; is is able to respond to new incoming requests for more HelloWorldThreadFile djinns. Forexample, if someone else summoned my HelloWorldThreadFile djinn while I have one running,that summon request will be forwarded to the running HelloWorldThreadFile djinn, the II willautomatically start up a new instance of the djinn, and we’ll have two HelloWorldThreadFiledjinn running at the same time in the same Java run-time.

If all of the above is correct, I can summon that djinn with the command:

java info.demo.summoner.Summoner -m lute.cs.caltech.edu 9876 -d HelloWorldServerThread -u kiniry

I use the port number 9876 because this is the default port on which the Djinn Master runs.If I wanted the Master to run on some other port, I can use the -iip flag. For example, if I wishthat the Master run on port 10000, I use the command “master.sh -iip 10000”.

And there you have it; my HelloWorldThreadFile djinn is running inside of the Djinn Master,I see it prints out “Hello World!” five times and exits. When it exists, it automatically saves its


persistent state (nothing at all for this particular djinn) and leaves the Djinn Master exactly asit was before the djinn started up.

Note that, when you wish to shut down a running Djinn Master, you should not (unlessnecessary) send a break/kill signal to the process. Meaning, in general, one should not hitcontrol-C, use the “kill” command in UNIX, or use the “end task” service in Windows to stopthe Djinn Master. The Djinn Master is a djinn just like any other, so it should be shut downin an orderly fashion so it can save its persistent state and clean up after itself. To do so, oneuses the Summoner djinn with the special command line argument of -M (or the Dispell Masterbutton on the GUI) to denote to the Summoner that one is dispelling a running Djinn Master.

For example, my Djinn Master from the above exercise is running on lute.cs.caltech.edu’sport 9876. To dispell this Djinn Master I use the command:

java info.demo.summoner.Summoner -m lute.cs.caltech.edu 9876 -i lute.cs.caltech.edu 9876 -d info.master.DjinnMaster -u kiniry -D -M

The -m and -i switches tell the Summoner exactly where the djinn in question (my DjinnMaster) is running. Note that, with respect to the Summoner, a Djinn Master’s Master is itself.(If you actually look at the DjinnName of a running Djinn Master you will note that it does nothave a master location, unless of course it was run as a djinn inside of another Djinn Master, butthis degree of recursion is another exercise altogether.) The -d switch informs the Summonerthat the instance name of the djinn in question is info.master.DjinnMaster. Recall that a djinn’sinstance name is its main class name if an instance name was not specified on the commandline (with the -iin switch and, given our above example, we did not specify such a name sothe default name is the main class of the Djinn Master: info.master.DjinnMaster. Finally, the-u switch is indicating who’s Djinn Master we are attempting to shut down and the -D and -M

switches are denoting that we are contacting a Djinn Master with the explicit and sole purposeof shutting that Master down.

6.2 HelloWorld

No set of examples would be complete without this classic favorite. This is the standard “first-program-I-learned” sort of example.

The HelloWorld djinn runs continuously, printing Hello, World! over and over again onstandard out a total of five times. It tests the support for non-terminating djinns (if we let itprint forever). It performs no networking whatsoever.

To use this example:

1. Check that a line similar to the below is in your dmrc file:

HelloWorld info.demo.helloworld.HelloWorld URL thread,instance

2. Replace the above URL with a valid URL from which the class info.demo.helloworld.HelloWorldclass can be loaded (see the previous section for a more in-depth discussion of this point).

6.2. HELLOWORLD 73

3. Start this djinn with the Summoner, as detailed in the previous section.

Here we will include the second (and final) full example of the use of the Summoner tosummon a djinn. To show exactly which steps and issues impact running such a djinn, we willjust cut-and-paste the keystrokes we used to start up the djinn. Again, the following is simplya cut-and-paste from two Xterms, one running on the machine lute.cs.caltech.edu and the otherrunning on oboe.cs.caltech.edu (note the command prompt).

First, the commands that I typed in to give the reader context on the machine lute.cs.caltech.edu,the system on which I plan to run my Djinn Master:

lute:ii_data> cd

lute:kiniry> cd ii_data

lute:ii_data> cat dmrc | grep -A 2 HelloWorldThreadFile



server,thread

lute:ii_data> ls -l

total 7

-rwxrwxr-x 1 kiniry info 28 Mar 26 13:55 clean_state.sh*

-rw-rw-r-- 1 kiniry info 1806 Apr 21 13:10 dmrc

-rw-rw-r-- 1 kiniry info 1231 Apr 21 13:24 master.res

-rwxrwxr-x 1 kiniry info 174 Mar 26 21:38 master.sh*

drwxrwx--x 2 kiniry info 512 Apr 22 14:10 state/

Now that you see where I am and what the entry in my dmrc looks like, I run my DjinnMaster:

lute:ii_data> master.sh


The above line “The Djinn Master...” indicates to you that the Djinn Master is running andis ready for action.

Now, I turn my attention to oboe.cs.caltech.edu, the system on which I am going to run mySummoner djinn. I can run this Summoner call from any location as long as my CLASSPATH isset up correctly. Thus, I just sit in my home directory and type in the command as dictated bymy choice of Djinn Master location, username, and djinn instance name indicated in my dmrc

file:

oboe:kiniry> java info.demo.summoner.Summoner -m lute.cs.caltech.edu 9876 -d HelloWorldThreadFile -u kiniry

Summoner: Interacting with djinn...

Master: lute.cs.caltech.edu/131.215.78.20 9876 II_SUMMONREQUEST_IN

Instance: null

DjinnOwner: kiniry

DjinnInstanceName: HelloWorldThreadFile

Args:

My name is : [

DjinnTrueName:

[ Djinn Name: Summoner Djinn

Version: 1.0

Release Date: $Date: 1998/01/23 23:06:46 $

Author: The Infospheres Team

Organization: Infospheres Group, Caltech

Email: [email protected]

Djinn URL: http://www.infospheres.caltech.edu/]


InstanceOwner: kiniry

InstanceLocation: oboe.cs.caltech.edu/131.215.78.12 3296 II_DJINN_IN

MasterLocation: null

InstanceName: info.demo.summoner.Summoner

Summoning Time: Tue Apr 22 21:24:53 GMT 1997

]

Performing action requested.

Calling summon now...

Summon succeeded, summoned djinn’s DjinnName:

[

DjinnTrueName:

[ Djinn Name: HelloWorld Example Djinn

Version: 1.0



Organization: Caltech Infospheres Research Group




InstanceLocation: lute.cs.caltech.edu/131.215.78.20 2834 II_DJINN_IN

MasterLocation: lute.cs.caltech.edu/131.215.78.20 9876 II_DJINNMASTER_IN

InstanceName: HelloWorldThreadFile


]

All done.

oboe:kiniry>

The Summoner djinn starts up, prints out what it is up to (whom it is contacting, thevariables involved in the summons, and what the Summoner’s DjinnName is), and summonsthe remote djinn. The summon call succeeds and the DjinnName of the remote djinn (theHelloWorldThreadFile) is returned and printed out. On the remote side (lute.cs.caltech.edu),the following is printed out (we are including the last line of the previous output for context):


Hi there, I’m [ Djinn Name: HelloWorld Example Djinn

Version: 1.0



Organization: Caltech Infospheres Research Group



Hello, World!

Hello, World!

Hello, World!

Hello, World!

Hello, World!

The HelloWorldThreadFile djinn (AKA, the info.demo.helloworld.HelloWorld object)runs, prints out its DjinnTrueName, and then does its job; in this case this means printing outthe string “Hello, World!” five times. The djinn then saves its persistent state and exits. Now,I’ll shut down the Djinn Master on lute.cs.caltech.edu from oboe.cs.caltech.edu:

oboe:kiniry> java info.demo.summoner.Summoner -m lute.cs.caltech.edu 9876 -i lute.cs.caltech.edu 9876 -d info.master.DjinnMaster -u kiniry -D -M

Summoner: Interacting with djinn...

Master: lute.cs.caltech.edu/131.215.78.20 9876 II_SUMMONREQUEST_IN

Instance: lute.cs.caltech.edu/131.215.78.20 9876 II_SUMMONREQUEST_IN

DjinnOwner: kiniry

6.3. RECURSIVE 75

DjinnInstanceName: info.master.DjinnMaster

Args:

My name is : [

DjinnTrueName:

[ Djinn Name: Summoner Djinn

Version: 1.0



Organization: Infospheres Group, Caltech




InstanceLocation: oboe.cs.caltech.edu/131.215.78.12 3378 II_DJINN_IN

MasterLocation: null

InstanceName: info.demo.summoner.Summoner


]

Performing action requested.

Calling dispell now...

All done.

oboe:kiniry>

When dispelled, the Djinn Master on lute.cs.caltech.edu simply prints out the line:

Hello, World!

The Djinn Master has been dispelled, quitting.

lute:ii_data>

And that’s the whole example.

6.3 Recursive

The Recursive djinn is very similar to the Hello World djinn, in that its only interaction withthe user is to print a message on the screen when it is summoned. However, when summoned,it also summons another Recursive djinn from the same Djinn Master, which summons anotherRecursive djinn from the same Djinn Master, which summons another Recursive djinn from thesame Djinn Master, which...

The purpose of this demo is to show that not only can we start up a whole lot of djinnsinside the same Djinn Master, but also to illustrate the concept of parent djinns (note that eachRecursive djinn displays the DjinnName of its parent when it runs).

The Recursive djinn cannot be started from the command line - it must be started by theSummoner or by another djinn, and it must run inside a Djinn Master. Additionally, it mustrun in instance mode. If you try to run it outside a Djinn Master, or in server or muxl mode,it will complain and exit gracefully. It takes a single command line argument, an integer whichspecifies the number of Recursive djinns which remain to be summoned (so passing it ”5” wouldresult in the creation of a total of 6 Recursive djinns - the initial one, plus five more).

To run this demo, add a line like the following to your dmrc file:

RecursiveDjinn info.demo.recursive.RecursiveDjinn URL instance,thread

and then use the Summoner to summon a RecursiveDjinn in a running Djinn Master, passingto it the number of instances you wish to see recursively summoned.


6.4 Calendar

The Calendar suite is the first fully-functional application built on top of the II. It is a rudi-mentary calendaring system, which uses a command-line interface (SimpleCalendarInterface) tocommunicate to Calendar servers (CalendarDjinn) on multiple machines. It makes use of tokenpassing for distributed mutual exclusion, so that no conflicting appointments are ever made.

To run this demo, add a line like the following to your dmrc file:

CalendarDjinn info.demo.calendar.CalendarDjinn URL server,thread

Detailed information on the use of the Calendar djinn can be found in the javadoc documen-tation of the info.demo.calendar package.

6.5 Dictionary

This is an example of a djinn which (a) is invoked by a front end object in a client-server fashionand (b) interacts with a third party program that is not part of the II, in particular, it interactsvia TCP with a Webster daemon.

The WebsterClient class is the front-end that queries the back end (WebsterServer for worddefinitions. The WebsterClient goes through the following steps:

1. First, in the initDjinn method, the WebsterClient creates its two mailboxes; an anony-mous Sendbox and an anonymous Receivebox. When creating the Receivebox, it use aFilter, specifying that only Place objects will be accepted on that Receivebox. Note thatan “anonymous” Mailbox means that the Mailbox is not explicitly named by the program-mer; it is letting the MailDaemon uniquely name the mailbox in question.

2. The WebsterClient does not have a thaw method, so there is no persistent state to load.The default thaw stub of the djinn class is called next with no effect.

3. The WebsterClient djinn next, after checking the command line arguments, summons aWebsterServer on the remote machine specified by said arguments. It passes to the remotedjinn (the WebsterServer) as parameters the String representation of its Receivebox. It doesthis so that the WebsterServer knows where the WebsterClient is waiting for a message(see the next few steps). The WebsterServer can parse this argument and wire its Sendboxup to this destination with a bind call and thus send messages to the WebsterClient.

4. The WebsterClient djinn next calls the getConnected method, a method specific to Web-sterClient, and therein expect to receive a message on its Receivebox.

5. After receiving a message, (necessarily of type info.net.Place because the Filter we in-stalled when the Receivebox was constructed), the WebsterClient binds its Sendbox tothat specified Place. Also, the WebsterClient at this time puts a new Filter in place on itsReceivebox, specifying that only messages of type info.demo.dictionary.Response will be

6.5. DICTIONARY 77

accepted. Note that messages of type info.net.Place will no longer be accepted after thisnew Filter is put in place.

6. The WebsterClient then queries the user with the string “(D)ictionary, (T)hesaurus, [Q]uit:”.The user is expected to input either a ‘d’, a ‘t’, or a ‘q’. If a dictionary or thesaurus queryis requested, the WebsterClient queries for a word to process. If the user demands that theWebsterClient shut down, it sends a “DIE” message to the WebsterServer so that it canshut down properly, then itself shuts down.

7. If a definition or thesaurus lookup is requested, the word that is typed in by the user is sentin a Query object via the grab method of WebsterClient out its Sendbox to the Receiveboxof the WebsterServer.

8. The WebsterClient then waits on its Receivebox, expecting that the WebsterServer will sendthe result (a definition, thesaurus entry, or error) back via that channel. After it receivesthe response, it prints it out for the user and loops back to the original “(D)ictionary,(T)hesaurus, [Q]uit:” prompt.

On the flip-side, the WebsterServer has the following behavior:

1. In initDjinn, the WebsterServer constructs its mailboxes in a manner similar to the Web-sterClient. It sets up a filter, specifying that only messages of class info.demo.dictionary.Queryare accepted on its Receivebox.

2. The WebsterServer does not override thaw or freeze, so the default stubs for said methodsare used.

3. Next, djinnMain is called. The first thing djinnMain does is call setArgs, a methodspecific to the WebsterServer. setArgs first calls makeWebbie to set up the TCP connectionto the webster server that was specified on the command line of the WebsterClient (passedto the WebsterServer as part of the summons). setArgs then sends the address of its primaryReceivebox to the djinn that summoned it (the WebsterClient) via the address (Place)that was specified as part of the summons (see the above discussion of the WebsterClient’ssummon argument in relation to its command line arguments).

4. Next, back in djinnMain, the WebsterServer sits and waits for a message on its Receivebox.When it receives a message, it looks at the message’s “type” (via the is method) todetermine whether the request is for a definition, a thesaurus query, or a quit (“DIE”)message.

5. Finally, the WebsterServer responds appropriately to the message, either performing thelookup via the ProcessQuery method, or shutting down by exiting djinnMain. If a queryis requested, its response is sent back to the WebsterClient and the WebsterServer loopsback to the “waiting for a message” state discussed above.



1. A line like the following should be in your dmrc file:

WebsterDjinn info.demo.dictionary.WebsterServer URL server,thread

To reiterate (one again, and the last time) the URL is a valid, comma separated, pointy-bracket delimited, URL path to the Infospheres class tree (as all the other examples).Example URLs include a URL like <file:/info/source/> for local class loading or<http://www.mysite.com/infospheres/> if the class files are visible to your web server.

2. Run a Djinn Master as in the previous examples (or reuse the one you still have running).

3. Run the WebsterClient from the command line and request the definition or thesaurusentry for a word. For example, for a Master running on the system stun4z.cs.caltech.edu,port 9000:

java info.demo.dictionary.WebsterClient kiniry lute.cs.caltech.edu 9000 WebsterServer webster.caltech.edu

There are several things to note about this example djinn:

1. The implementation of TCP sockets is not correct on some versions of JDK 1.0. In par-ticular, if you attempt to run this demonstration with your Djinn Master running on aNetBSD system, running the Linux port of JDK 1.0.2, you will get a SocketException

and the demo will fail.

2. We have left the debugging output turned on in this release of the WebsterServer.

3. Most webster servers run with a very short connect life. This means that the first connectionto the webster daemon is made when the WebsterServer is summoned. If you, the use, takelonger than a couple of seconds in typing in your word to define, that connection to thewebster daemon will go stale, the WebsterServer will throw a SocketException, and thenit will automatically reconnect to the webster daemon to pull the definition for you. Wejust wanted to make sure that no one got upset at the exceptions flying around in thedebugging output.

6.6 Date

This is another example of using service requests in the Infospheres Infrastructure. A client djinnprovided summons a server djinn, and makes a service request on it via its lamp (that is, it callsthe lamp.server method). The response returned is the date on the remote djinn’s machine,which is then displayed.

More precisely, the DateClient summons the DateServer via a Djinn Master. The DateClientthen uses its lamp’s service method to send TimeRequest to the running DateServer. The

6.7. PERSISTENT 79

DateServer’s service method is called, it does the lookup for the local time, and returns theproper TimeResponse. If the answer the client gets back is a TimeAnswer, it prints the remotemachine’s current time and date to stdout. If the answer it gets back is something else, it printsan error message.


1. Add a line similar to the following to your dmrc file (and follow the instructions with regardto such entries found elsewhere in this chapter and in the rest of the User Guide):

DateServer info.demo.date.DateServer URL server,thread

2. Execute the DateClient djinn with a command similar to the following:

java info.demo.date.DateClient kiniry lute.cs.caltech.edu 9876 DateServerThread

The client will query the server and then print out the time and date that the remote machinereported.

6.7 Persistent

This djinn keeps track of how many times it has been instantiated, and responds to servicerequests for this instantiation count.

This a generic example of using the lamp’s service method with a non-default service sub-class. Meaning, we are not just sending a ServiceRequest over the wire, we are sending, in thisdemonstration, a InstCountReq which is a subclass of ServiceRequest. This is also an exampleof general persistence in djinns – PersistenceServer keeps track of how many times it has beeninstantiated and saves that information as part of its state.

The PersistentClient program summons a Persistent djinn on a remote machine, and requestsa InstCountReq service from it. The Persistent djinn returns a InstCount which indicates thenumber of times that this persistent djinn has been instantiated.


1. Add a line similar to the following to your dmrc file:

Persistent info.demo.persistent.PersistentServer URL thread,server

Where URL is a valid URL path to the Infospheres class tree, whether it be a URL likefile:/info/source/ for local class loading or http://www.mysite.com/infospheres/ ifthe class files are visible to your web server.

2. On another machine, execute a command similar to the following:

java info.demo.persistent.PersistentClient kiniry oboe.cs.caltech.edu 9876 PersistentFile master


There are a few things to note about this example. First, the final parameter of Persistent-Client is either “master” or “instance”. The value of this parameter indicates to the Persistent-Client whether it is contacting a Djinn Master (with a Summons then a service request) or aninstance of a PersistentServer that is already running, perhaps independent of a Djinn Master.

For example, it is equally valid to run PersistentServer from the command line, read off thevalue of its InstanceLocation (the Place where that PersistentServer’s MailDaemon is listening),and use those values as the second and third parameters of PersistentClient, thus connecting toa running djinn directly, without the intervention of a Djinn Master.

6.8 OutboxAssoc

The OutboxAssoc example is a quick demonstration of outbox associations. It consists of twodjinns, OutboxAssocClient and OutboxAssocServer. OutboxAssocClient is run from the com-mand line, and provided with the location of a remote Djinn Master. It then summons anOutboxAssocServer using that Djinn Master, with a set of 2 outbox associations pointing backto 3 Receiveboxes it has created (one association points to one Receivebox, the other points tothe other two - this forces the server side to create one Sendbox and one Broadcastbox).

The summoned OutboxAssocServer, on startup, prints its outbox association table and sendsmessages on the outboxes in its outbox association list. Assuming that the outbox associationswork the way they are expected to, the OutboxAssocClient then receives the messages “6, 42,42” on its boxes, prints this fact, and exits.

For this demonstration to work properly, a line like the following must be present in yourdmrc file:

OutboxAssocServer info.demo.outboxassoc.OutboxAssocServer URL server,thread

Then, after starting a Djinn Master on one machine, the demonstration can be started byexecuting a command similar to the following:

java info.demo.outboxassoc.OutboxAssocClient dmz sousaphone.cs.caltech.edu 9876 OutboxAssocServer

The client and server will both display reasonable error messages if something goes wrongwith the demonstration.

6.9 Middle

The Middle djinn is something of a pun on “Middle-Management”. This djinn was written toshow off and test the ability of a summoned djinn summoning another djinn. Meaning, we wishto make sure that you can build an arbitrarily long chain of summoned djinns.

Again, you need a line in your dmrc file similar to the following for this demonstration towork:

MiddleDjinn info.demo.middle.MiddleDjinn URL server,thread

6.10. TOKENPASSER 81

The first time you summon this djinn, nothing special happens; it just starts up and runsin server mode, waiting for more messages from its environment. If you summon it again youwill receive a handle on the same instance because it is running as a server. To activate theMiddle djinn’s special behavior, you must pass it the appropriate arguments, more specifically,arguments very similar to that which Summoner uses, for it to parse. Those arguments will tellthe Middle djinn to summon yet another djinn specified by said arguments. An example is inorder.

6.10 TokenPasser

Since the Djinn Initiator is not included with this release of II, the TokenPasser does not work.However, one can still look at the code for the TokenPasser djinn if the reader is interested inhow it works.

This example shows of the capability of the II to automatically “wire-up” a network ofcomponents. This example starts up a number of TokenPassers, djinns whose sole purpose inlife is to pass a token around each of which print out a message when they receive the token andwhen they send the token away. A collection of these djinns pass a token (or tokens) around likea hot potato, and you get to watch!

The TokenPasser receives a token (represented by the TokenMessage class) on its PrevToken-Passer inbox, holds it for a short time, and then sends it out on their NextTokenPasser outbox.This djinn is an example of connecting a multi-node session using the Initiator.


1. Add a line similar to the following to your dmrc file:

TokenPasser info.demo.tokenpasser.TokenPasser URL instance,thread

2. Run a several (at least two) different Djinn Masters, either on different systems or ondifferent ports of the same system (use the “-iip” flag).

3. Start the Djinn Initiator if you have not already done so. See the Tools chapter for moreinformation on the use of the Initiator.

4. Load the session file called TokenPasser.di using the File:Open menu option.

5. Edit the network layout to reflect the Djinn Masters that you started. This means eitheradding or deleting nodes in the personal network that represent TokenPasser djinns andediting each by double clicking on it.

• Change each username to the owner of the dmrc that was changed above (that is, yourusername).

• Change each computer name to a computer running your Djinn Master.

6. Select the Code:Send to Djinn Master menu option.


6.11 Test Suite

The client-server test suite tests a whole set of functionality with respect to djinn – djinn inter-action and djinn – djinn master interaction. Since we keep adding tests to the suite, please seethe source code of these djinns for information on the tests that this package performs.

6.12 Applets

An example applet that extends info.djinn.DjinnApplet is provided in the form of info.demo.applet.HelloWorldApplet.This applet can be run from the command line (unlike a normal applet, but like a normal djinn),or can be run with the appletviewer included with your JDK. The applet just prints out a set ofmessages and shuts down.

6.13 DispellButton

DispellButton provides a convenient, tidy way to call the dispell() method of a Djinn. Eachinstantiation of a ”dispellable” Djinn (see DispellableExample for what this means) creates asmall window containing a ”Dispell” button labeled with the name of the Djinn it dispells.When the Button is pressed, the window goes away or not, depending on the success of thedispell() call. The dispell() method of the ”dispellable” Djinn then sets a flag which makes theDjinn go away.

A DispellButton can be used only within a ”dispellable” framework. This is explained indetail in the javadocs and code.

Verify that your DMRC contains entries analogous to the following. You’ll replace ”Dis-pellableExample” with the name of your dispellable Djinns, and note that your DispellButtonand your dispellables are ”instance”s:

DispellableExample info.demo.dispellbutton.DispellableExample \

<file:/d|/mack/info/source/> \

instance, thread

DispellButton info.demo.dispellbutton.DispellButton \

<file:/d|/mack/info/source/> \

instance,thread

Some notes: Many DispellButtons may simultaneously exist; each one will be instantiatedat the same location, covering the others if you haven’t moved them, so don’t lose any! Thewidth of the window is fixed, but the length of a DjinnName is not, so you may find the label istruncated.

Appendix A

Debugging II Djinns

A.1 Debugging Output in the II

All debugging output in the II is now routed through one class: info.util.Debug. Errors inthe info.net package used to be routed through the info.net.Debug class, but that classesfunctionality has now been rolled into info.util.Debug. To fine-tune debugging output, lookinto both of these simple classes and modify to taste. We have a much more comprehensivedistributed debugging methodology and set of tools built for the II2.0 (to be released in 1Q98),but decided not to retrofit that work into this final release of the II1.0.

A.2 Submitting Bug Reports

The more information we have, the easier and more likely it is we will fix the bug. Please supplyall of the below information and mail it to [email protected]. If you would like ourcurrent list of bugs mailed to you, please email us. In future releases, we plan to a form-basedbug reporting mechanism. Make sure you provide all the below information with your bug report.

• Operating System and Version:

• Java Port and Version:

• Infospheres Infrastructure Version:

• Example Code:

• Exception/Thread Trace:

• Comments:

• Contact Information:

83

84 APPENDIX A. DEBUGGING II DJINNS

A.3 Known Bugs

Known bugs are listed in section 1.7.

Appendix B

Glossary

Component — A component is a stand-alone set of code that can plug-and-play across net-works, applications, languages, tools, and operating systems. Distributed objects are com-ponents by definition, but not all components are objects (as per Ted Lewis’ IEEE Com-puter Column, May 1996). Components are often engineered to solve a particular problem,often in a business model. For example, a customer, a purchase order, an automobile, anda shopping basket are all examples of business components. Components in this domainare often called Cooperative Business Objects (CBOs). Optimally, components should bemarketable, goal-specific, flexible, well-defined, interoperable, and extensible.

Djinn — A Djinn (Distributed Java Infosphere Network Node) is the fundamental componentin the Infospheres Infrastructure. Djinns are components in the classical sense: they aredistributed applications of varying size that perform specific tasks by working in tandemwith other distributed services, djinn or otherwise. Djinns have well-defined interfaces thatallow them to be accessed by other djinns, and can be extended through encapsulation andaggregation.

Djinns are written using the Infospheres Infrastructure packages; alternatively, they can bedynamically generated with the Djinn Initiator and Djinn Generator GUIs. Djinns can beused to encapsulate a variety of services: simple C, C++, and Fortran processes, distributedCORBA and COM objects, object libraries and frameworks, legacy business applicationswritten in older languages or systems such as COBOL and MVS, traditional DBMS andfilesystems, and non-traditional arbitrary processes with deterministic interfaces. Djinnsare primarily used to compose sessions.

Djinn Master — The Djinn Master is responsible for the instantiation of, and the initialcommunication to, persistent djinns in a distributed application or session. The DjinnMaster maintains a table of current djinns running; if a request for a djinn is made, andthat djinn is not currently running (or does not currently exist), the appropriate djinn isthawed (or initiated) and executed, and the request is forwarded to the djinn.

This mechanism is similar to the BOA (Basic Object Adaptor) of CORBA, except that weonly provide three server models: that of server per request, that of persistent server per

85

86 APPENDIX B. GLOSSARY

session, and that of a locked server (that is, the server is only allowed to participate in onesession at a time). Also, the Djinn Master is much more lightweight than a CORBA ORB,and it is more flexible since it can initiate arbitrary processes whether or not they conformto the Infospheres Interface specification. We have a prototype Djinn Master available inJava.

Djinn Initiator — The Djinn Initiator is a stand-alone Java program that allows its user toconstruct a distributed session graphically. The session is depicted as a directed graph,whose nodes represent the djinns, and whose edges represent the bindings between Inboxesand Outboxes. Sessions described in this manner can then be initiated through communi-cation with Djinn Masters on the remote systems designated in the Djinn Initiator.

Djinn Generator — The Djinn Generator is a stand-alone Java program that allows its userto construct a djinn visually with a table that represents the states of the djinn, and pro-gram code corresponding to what the djinn should do in each of those states for each of aspecified set of nodes. This model is being extended such that one can automatically gen-erate needed djinns during the construction and instantiation of a session of djinns. Theseauto-constructed djinns can complete specific, simple tasks like byte-stream conversionsand logging. This piece of the Infospheres Infrastructure is still very much in its infancybut does generate compilable and runnable Java code.

Freeze — Freezing a djinn involves capturing its state and saving it in a persistent file. Suncalls this the “pickling” of objects; it is also called “serialization.” A frozen djinn can bethawed and executed again, either locally or remotely, though a message to its appropriateDjinn Master, which summons the djinn using a lamp. Note that the program counter ofa djinn is not saved when the djinn is frozen; when the djinn executes again, it is restartedfrom the beginning. Also note that when a djinn is not being used, it is frozen; when itgets an incoming message, it is thawed. A djinn can also save its state but not necessarilyexit by using the checkpoint method.

Infosphere — Infosphere is a term coined by the military; a person’s Infosphere includes thecollection of instruments, appliances, computing tools, services, and people accessible froma person’s environment, wherever that may be (for example, in the office, on a plane,or at the bridge of a ship). Djinns are an enabling technology that make Infospheresconstructible. Thus, an Infosphere is a personal collection of djinns; alternatively, anInfosphere is a collection of related djinns that are applied by a person to accomplish aparticular task.

For example, as I write this document, I am in paper-writer mode and I use a specific setof tools: emacs, framemaker, a Web browser, LATEX, and xdvi. These tools can all beencapsulated in djinns to become part of my Paper Writer Infosphere. Later, when I’mcorresponding with colleagues, I’ll be in Email/Letter-Writer Mode, and my set of toolswill differ slightly. And then, even later, after I’ve had a pot of coffee and a few candybars,I’ll be in Software Developer Mode as I write, compile, test, and debug source code. using

87

emacs, javac, java, javadoc, and other tools, which can all be encapsulated in djinnsin a new Infosphere! We will be providing tools in the future to support the notion ofInfospheres in a regular and integrated fashion (tying in with your desktop and browsermetaphors).

II — The II (Infospheres Infrastructure) is the collection of Java middleware packages thatsupport the development of djinns and sessions of djinns. These include the class librariesfor mailboxes and messages, the package for writing djinns, and stand-alone programs likethe Djinn Initiator and the Djinn Master.

Interface — An Interface is a set of publicly-accessible methods related to an object. Fordjinns, it is the set of public methods on the djinn subclass that a program can use. ForJava objects that can be accessed only locally, Java interfaces or abstract classes (an nowintrospection) can be used to construct the interface of the object. If, on the other hand,your djinn is going to interoperate in a distributed fashion, you must use the providedframework djinn object, which provides a standard set of methods for object maintenanceand communication.

For a future release (perhaps version 2.0 of the package), any djinn that is constructedwill use the MIO (Meta Infosphere Object) methodology and will have its interface definedindependent of the implementation. This definition might take the form of a speciallyorganized HTML or XML document.

This file will contain, among other things, an interface definition written in some InterfaceDefinition Language (IDL). This IDL can be used to construct your djinn interface eitherstatically or dynamically. If your object’s interface is fairly stable, you will use an IDLcompiler/stubber to generate a code skeleton. This skeleton provides all of the commonfunctions of your djinn’s interface. If your object is dynamic, mutable, or a prototype, youare likely to use the dynamic interface builder which does its work “behind-the-scenes,”though at a significant performance penalty at object instantiation.

Lamp — A Lamp can be visualized as the object in which the djinn lives and through whichit interacts with the outside world in an organized, regular fashion. For example, whenone djinn (call it A) wishes to call another djinn (B) into existence so that they can worktogether on a problem, it invokes that djinn with what is called the “summon” operations.That is, A summons B via A’s lamp object. The lamp also lets A request “services” fromB and “dispell” B when B is no longer useful to A.

Mailbox — A Mailbox is an object that facilitates message passing between djinns. The basicMailbox can be used to send typed messages to specific mailboxes and to receive typedmessages from arbitrary Mailboxes. Many provided objects increase the functionality ofthe basic Mailbox (two examples are filters and sets). Furthermore, through inheritance,more specialized mailboxes can be constructed (the primarily examples being Inboxes andOutboxes). These classes offer greater functionality, such as message queuing and target


destination binding. Each Mailbox has a unique name on the Internet, called a Place. Thisallows for messages to be routed to specific mailboxes anywhere on the Internet.

MailDaemon — The MailDaemon is the object, unique to each djinn, that controls the flowof messages through the djinn’s ports. It routes incoming messages to the appropriatemailbox, and ships outgoing messages to the correct target djinn. The MailDaemon ensuresthat all messages are ordered point-to-point, and that there is no duplication, loss, orcorruption of any message.

Message — The Message class is the base class for any object that is shipped between Mail-boxes. Messages have provisions for serialization and de-serialization, as well as remoteclass loading if a specific Message child’s byte code is not found locally. Each Message typehas an associated unique identifier (currently, this is an URL) that can be used to find thebyte code associated with that Message. This identifier is shipped along with the Messagefacilitating dynamic class loading. This, of course, can be dangerous if done blindly, so thereis a security object that monitors the arriving URLs and determine whether they shouldbe trusted for their byte codes or not. To make a Message child object, all a programmerneeds to do is implement two methods, writeData and readData. These methods takeDataInput/OutputStreams as parameters, and so serializing and de-serializing an object isbasically as simple as reading and writing it from a file. Furthermore, multiple Messagescan easily be wrapped in a single message with dynamic type casting and instantiationtechniques provided by Java.

Object — An object is the encapsulation of behavior and/or data in a programmed unit; whenan object encapsulates both behavior and data, we refer to it as a component (for example,a djinn is a component). One research question the Infospheres Group is investigatingis allowable behaviors of djinns. Many of the Java classes provided with the Infospherespackage allow the creation of objects such as Mailboxes and Messages; the behavior of anobject is controllable through its interface.

Place — A Place is a unique tag for a specific Mailbox. It is composed of the local machine’sIP address, the port number being listened on by the MailDaemon associated with thedjinn, and a locally unique string name. Places are also Messages, which means that theycan be shipped over the network and used on remote nodes. These objects allow djinns tocommunicate with one another and pass information of the whereabouts of djinns to thirdparties.

Process — A process is one of two kinds of compositional units (the other being a session).A process is a (potentially multi-threaded) component that encapsulates the state of itscorresponding document or appliance. In a reliable distributed system, state can only bemodified by a process in systematic ways (for example, only by an authenticated protocol).In our implementation, a process is a Java program with files (that is, persistent state)— called a djinn in our jargon — that can interact with other processes by sending andreceiving messages through its Inboxes and Outboxes. We can reason about a process

89

as a state transition system; the state of a process includes the states of its Inboxes andOutboxes. Process specifications are given in terms of safety properties (for example, next,stable, and invariant) and progress properties (defined using leads-to). Processes can onlybe composed in parallel; we do not deal with sequential or choice composition of processes,though we do support sequential and choice composition of sessions.

Servlet — A servlet is one of the many service classes we will be providing in a future releaseof the Infospheres Infrastructure that facilitates multithreaded and distributed system pro-gramming. These constructs will let us reason about the distributed system as a whole, asopposed to reasoning about specific pieces. Currently, the set of classes we are working oninclude: Distributed Data Structures, Layering Stacks, Logical Clocks, Reusable Barriers,Single-Assignment Variables, and Tokens. Note that we do realize that the term servlet isnow overloaded with Sun’s release of the Java Server. We’ll likely rename our packages foryour protection.

Session — A session is one of two kinds of compositional units (the other being a process).A session is a collection of processes composed in parallel; a session is specified in termsof the precondition and postcondition predicates of its component processes. Sessionscan be composed using sequential and choice composition, and we reason about sessionsusing theory from the field of sequential programming. Distributed applications can bestructured by nesting processes and sessions, and the Infospheres Infrastructure supportssuch capability. For example, a developer can use the Djinn Master to design a session as adirected graph, whose nodes are djinn (possibly designed using the Djinn Generator), andwhose edges are bindings between mailboxes (constructed using the maildaemon package).The Djinn Master can initiate sessions described in such a manner.

State — The State of a djinn consists of the values of all of its variables that need to be savedto keep the djinn persistent. A djinn’s state is stored when it is frozen, and it is restoredwhen the djinn is thawed.

Thaw — Thawing a djinn involves resurrecting its state from a persistent file, resetting itsprogram counter, and starting its execution. Sun calls this the “unpickling” of objects; itis also called “deserialization.” A frozen djinn can be thawed and executed again, eitherlocally or remotely, though a message to its appropriate Djinn Master, which summons thedjinn using a lamp. Note that when a djinn is not being used, it is frozen; when it gets anincoming message, it is thawed.

Type — A type is the abstract representation of a variable or object. In the non-object world,all variables have a type in the traditional sense. These types are either derived frommathematics (integers, reals, symbols), are collections constructs (array, vector, stack),are aggregates of constructs (structs, bags, unions), or are references to typed constructs(pointers, references). In object systems, the type of an object is either falls into one ofthe aforementioned categories or is a class. A class is a description of an object’s state and


interface. So, in the Infospheres context, a type is the union of types and classes in thetraditional sense.

Virtual Network — A Virtual Network is a set of objects and bindings of Outboxes andInboxes. It can be represented as a labeled directed graph in which the vertices are objects,and the edges are directed from Outboxes to Inboxes and are labeled with the (Outbox,Inbox) pair. Two-way communication between objects is represented by bi-directionaldirected edges. It is not necessary that every Outbox be bound to some Inbox, nor thatevery Inbox be bound to some Outbox in each Virtual Network. A Personal Network is aVirtual Network that is built by and for and single individual to fulfill a single task.

II: The Infospheres Infrastructure User Guidedmz/resources/ii.pdf · Chapter 1 Introduction 1.1...

Documents

Transcript of II: The Infospheres Infrastructure User Guidedmz/resources/ii.pdf · Chapter 1 Introduction 1.1...