The Agent ORB for Java Core Technology User Guide Version 1.0.0 © 1997 ObjectSpace, Inc. All rights reserved. ObjectSpace, Inc. has used its best efforts in preparing this book. These efforts include the development, research, and testing of the theories and programs to determine their effectiveness. ObjectSpace, Inc. makes no warranties of any kind, expressed or implied, with regard to these programs or the documentation contained in this book. ObjectSpace, Inc. shall not be liable in any event for incidental or consequential damages in connection with, or arising from, the furnishing, performance, or use of these programs. ObjectSpace Voyager and Space are trademarks of ObjectSpace, Inc. Java is a trademark of Sun Microsystems. All other brand or product names are trademarks or registered trademarks of their respective holders. RESTRICTED RIGHTS LEGEND: ObjectSpace Voyager is furnished under a license and may not be used, copied, disclosed, and/or distributed except in accordance with the terms of said license. This document and all online system documentation are © 1997 by ObjectSpace, Inc. All rights reserved. No portion of this document may be copied, photocopied, reproduced, transcribed, translated, or reduced into any language, in any form or by any means, without the prior written consent of ObjectSpace, Inc. This document is subject to change without notice. Part No. DOC-3000-00 Software Version 1.0.0 First Edition Printed in the United States of America Table of Contents Preface.......................................................................................................................viii Purpose and Audience.........................................................................................viii How to Use This Document ................................................................................viii Notational Conventions.......................................................................................viii Related Documents................................................................................................. x Directory Layout .................................................................................................... x Example Programs ................................................................................................. x Technical Support.................................................................................................. xi Free Support.................................................................................................... xi Annual Technical Support Contracts.............................................................. xi Problem Reports and Suggestions........................................................................xii Product Updates ...................................................................................................xii Acknowledgments................................................................................................xii Part 1 ObjectSpace Voyager Overview 1 Introduction .......................................................................................................... 1 What Is Voyager?................................................................................................... 1 Future CORBA Integration .................................................................................... 2 Voyager Class Hierarchy........................................................................................ 2 Interfaces.......................................................................................................... 2 Classes ............................................................................................................. 3 Exceptions........................................................................................................ 4 2 Concepts ................................................................................................................ 5 Objects.................................................................................................................... 5 Voyager-Enabled Programs ................................................................................... 5 Remote-Enabled Classes and Virtual References .................................................. 6 Generating a Remote-Enabled Class...................................................................... 6 Constructing a Remote Object ............................................................................... 7 Sending a Message to a Remote Object ................................................................. 7 iii Table of Contents Connecting to an Existing Remote Object ............................................................. 8 Mobility.................................................................................................................. 8 Persistence............................................................................................................ 10 Agents................................................................................................................... 13 Space .................................................................................................................... 16 Message Types ..................................................................................................... 18 Dynamic Messaging............................................................................................. 19 Life Spans and Garbage Collection...................................................................... 19 3 Guided Tour........................................................................................................ 20 Introduction .......................................................................................................... 21 Phase 1: Building Stores....................................................................................... 22 Phase 2: Launching a Shopping Agent................................................................. 29 Phase 3: Buying an Item....................................................................................... 36 Part 2 ObjectSpace Voyager ORB 4 Introduction ........................................................................................................ 40 5 Fundamental ORB Features.............................................................................. 41 Starting Voyager Within a Program..................................................................... 42 Starting a Voyager Server from a Command Line............................................... 44 Remote-Enabling a Class ..................................................................................... 46 The vcc Utility ............................................................................................... 47 Setting Your CLASSPATH........................................................................... 47 Command Line Options................................................................................. 48 Cyclic References .......................................................................................... 52 VObject Methods ................................................................................................. 53 Movement ...................................................................................................... 53 Persistence ..................................................................................................... 53 Life Spans ...................................................................................................... 53 Properties ....................................................................................................... 53 Assistants and Listeners................................................................................. 54 Methods That Override Object Methods ....................................................... 54 Remote Construction and Messaging................................................................... 55 Remote Exceptions............................................................................................... 61 Storing and Passing Virtual References ............................................................... 63 Connecting to an Existing Object......................................................................... 67 Connecting via an Alias................................................................................. 67 Connecting via a GUID ................................................................................. 70 Remote Arguments, Serialization, and Morphology............................................ 72 Cyclic References................................................................................................. 74 ObjectSpace Voyager Core Technology User Guideiv Table of Contents Inheritance and Polymorphism............................................................................. 78 Interfaces .............................................................................................................. 82 Exceptions with Interfaces ................................................................................... 85 Life Spans and Garbage Collection...................................................................... 86 Reference-Based Life Spans.......................................................................... 86 Fixed Life Spans ............................................................................................ 87 Dynamic