Guaraná

Meta-objects can be combined through composers, that provide the glue code for them to work together, delegating control to them and resolving conflicts when they arise. Since composers are meta-objects, they can be further composed. Such a hierarchical composition mechanism is unique to Guaraná.

Unlike other reflective architectures, Guaraná was designed with security in mind, i.e., when a meta-object is associated with an object, it is impossible to steal control from it unless it is willing to waive it. Furthermore, composers can limit the reflective abilities of their component meta-objects and overrule their decisions. Meta-objects can create arbitrary operations addressed to objects they control, but composers can restrict the kind of operations their components can create.

In order to improve security, the identity of meta-objects is hidden from the base- and even from the meta-level. Nevertheless, Guaraná provides a mechanism to allow meta-objects to exchange information, or to introduce themselves to each other. To the best of our knowledge, Guaraná is the only reflective architecture with this kind of security concern.

Guaraná is language-independent and can be implemented atop other MOPs. We have implemented it by modifying the Kaffe OpenVM, a Free implementation of the Java(TM) Virtual Machine Specification originally by Tim Wilkinson (in the second picture on the right), CEO of Transvirtual Technologies, Inc. Note, however, that neither the Java programming language nor the Java bytecode format were modified, so any existing Java application can be made reflective by running it on our modified virtual machine.

Gallery

Richard Stallman (in the first picture on the left), the creator of the GNU project, has appreciated guaraná (a Brazilian soda :-) during his short visit to Brazil in 1996.

Tim Wilkinson (in the second picture on the right) invited me and Professor Buzato for some coffee (or should I say Kaffe? :-) in our short stay in California in October, 1998.

Doug Lea (in the second picture on the left), the author of the book Concurrent Programming in Java: Design Principles and Patterns, has pleased me with his presence at my presentation at the OOPSLA'98 Workshop on Reflective Programming in C++ and Java.

Jürg Gutknecht (in the third picture on the right), that created the Oberon system with Niklaus Wirth, has enjoyed guaraná (the soft-drink) when he came over for the Second Brazilian Symposium on Programming Languages, in 1997.

Roy Campbell (in the third picture on the left), the creator of the Choices reflective operating system, at the CS Department of the University of Illinois at Urbana-Champaign, has enjoyed the fact that, in the can of soft-drink he was given, he read ``Guaraná Champagne'' (that's the full name of Antárctica's guaraná soda :-).

On the right of the on-line documentation links, are pictures of some of the people I have met at COOTS'99: Douglas C. Schmidt, the main designer and developer of ACE and TAO; Robert C. Martin, from Object Mentor, lecturer and writer on OO modeling and XP; Steve Vinoski, from IONA Technologies, author of many articles, columns and one book about CORBA. Also on the right, I hold a bottle of Guaraná among the best-placed Brazilian team in the 1999 South American Regional Programming Contest, part of the ACM International Collegiate Programming Contest.

On-line documentation

• The Guaraná API: Produced by pizzadoc from the Guaraná 1.7 source files.
  • Last updated 01apr2001
  • 37Kb html gzipped tar-file
  • browsable html

• Composition of Meta-Objects in Guaraná: a paper that compares Guaraná with other MOPs, in terms of meta-object composition, and provides a short but almost complete description of the MOP. It is a good first reading about Guaraná, if you are already familiar with concepts of computational reflection and existing MOPs. A previous version of this paper was published as technical report IC-98-33. Accepted for presentation at the OOPSLA'98 Workshop on Reflective Programming in C++ and Java.
  • Last updated 24sep1998.
  • 62Kb gzipped postscript
  • browsable html

  

• The Design and Implementation of Guaraná: A description of the reflective architecture of Guaraná and some performance figures showing that the introduction of interception mechanisms cases a small impact on performance. Selected for presentation in the 5th USENIX Conference on Object-Oriented Technologies and Systems (COOTS '99).
  • Submitted on 06nov1998; notification of acceptance received on 18dec1998. Final version submitted on 23mar99.
  • 136Kb gzipped postscript
  • browsable html

• The Reflective Architecture of Guaraná: An updated version of technical report that contains an introduction to Computational Reflection and a full description of the reflective architecture of Guaraná. A previous version of this document is available as technical report IC-98-14.
  • Last updated on 20sep1998 (only minor formatting changes since 30jul1998)
  • 112Kb gzipped postscript
  • browsable html

  

• The Implementation of Guaraná on Java(TM): Describes the implementation of Guaraná on top of the Kaffe OpenVM, summarizing the role of each class and presenting some figures that compare the performance of Guaraná with the Kaffe OpenVM and Sun JDK. Some possible future optimizations are also outlined. Published as technical report IC-98-32.
  • Last updated on 19sep1998
  • 136Kb gzipped postscript
  • browsable html not available, latex2html could not handle the performance comparison tables :-(

• Guaraná: A Tutorial: Several examples and discussions covering from operation interception basics to dynamic reconfiguration and security details. Published as technical report IC-98-31.
  • Last updated on 20sep1998
  • 128Kb gzipped postscript
  • browsable html not available, latex2html could not handle the included programs and their outputs :-(

• Designing a Secure and Reconfigurable Meta-Object Protocol: A discussion about several of the design decisions of Guaraná, grounded on object orientation, security and flexibility. First published as technical report IC-99-08, but there's still much work left to make this a good paper.
  • Last updated on 12feb1999. On-line since 22dec1999.
  • 58Kb gzipped postscript
  • browsable html

• An Overview of MOLDS: A Meta-Object Library for Distributed Systems: A technical report that describes a library of meta-objects suitable for developing distributed systems, to be built on top of Guaraná. Previous versions of this document were published in the Proceedings of the Second Workshop on Distributed Systems (WoSiD'98), and as technical report IC-98-15.
  • Last updated 20sep1998, just minor formatting changes from 30jul1998's version.
  • 77Kb gzipped postscript
  • browsable html
  

• Guaraná: Uma Arquitetura de Software para Reflexão Computacional Implementada em Java: the final print of my Master Thesis. It contains the last four papers listed above, with an introduction and a conclusion in Portuguese.
  • Final version published on 15sep1998.
  • 336Kb gzipped postscript
  • browsable html not available, because some of the papers contained material that latex2html could not handle :-(

Releases

• 1.7 - April Fool's Edition: a maintenance release that fixes a number of bugs in previous releases and updates to 2001-04-01's snapshot of Kaffe 1.0.6, bringing in the various library and performance developments that have taken place in Kaffe since mid-1999. Released on 01apr2001.
  • outgoing interception: an experimental patch described here. To avoid having to rebuild guarana.jar, download the updated binary here. Released on 28jun2002, added here on 11nov2003 (oops, time flies! :-)

• 1.6: a major maintenance release. It features full integration with Kaffe (no more separate tar-files and downloads), much easier installation, a security fix in the reflective architecture and much faster garbage collection. Released on 01jun1999.
  • patch 1: interception of field operations requested through java.lang.reflect.Field was utterly broken, due to changes in the last release. Released on 13jun1999.
  • patch 2: float values wouldn't be wrapped correctly, because a work-around for a former bug in Kaffe was breaking it since the bug was fixed. Released on 09oct1999.
  • patch 3: fix some reconfiguration behavior that broke in some cases of Composer usage. Requires guarana.jar to be rebuilt and re-installed, by running make jar-classes in directory kaffe/libraries/extensions/guarana/javalib of the build tree. Released on 03feb2001, almost 16 months after it was installed in the CVS tree. Oops! :-)

• 1.5.1 - Brazilian Republic Day Edition: a maintenance release that updates to November 11's snapshot of Kaffe OpenVM 1.0.b2, and fixing a minor problem in the back-port of the wrapper scripts to the Kaffe 0.10.1 branch. This is probably the last release supporting Kaffe 0.10.1. Released on 16nov1998, a few hours after the end of the republic day :-(.
  • patch 1: the Kaffe 1.0.b2 branch would garbage collect meta-objects even if they are still associated with base-level objects. Released on 21nov1998.
  • patch 2: allows meta-objects to returnObject(null,op) when the operation expects an object return type, avoiding a NullPointerException. Fixed on 10dec1998, released on 11feb1998 (shame! :-)
  • patch 3: allows the creation of field write operations through operation factories. Fixed on 12feb1998, released on 20feb1998.

• 1.5 - Brazilian Patroness Day Edition: an update to Kaffe OpenVM 1.0.b2, introducing a few bug fixes and improvements, while still maintaining compatibility with Kaffe 0.10.1. Released on 12oct1998.

• 1.4.1 - Brazilian Independence Day Edition: a maintenance release that fixes a few problems in the last snapshot of Kaffe 0.10.1 and updates to September 10's snapshot of Kaffe OpenVM 1.0.b1, so you can still choose which one you wish to use. Released on 12sep1998, 5 days after the actual independence day :-(.

• 1.4 - Master Thesis Edition: based on both the last snapshot of Kaffe 0.10.1 and on August 19's snapshot of Kaffe OpenVM 1.0.b1, so you can choose whether you wish to keep running Sun's implementation of the Java Core Library (but without AWT) or the new clean-room implementation provided with Kaffe OpenVM 1.0.b1 (that includes AWT but, in other aspects, is still incomplet and inkorrect :-). Released on 22aug1998.

• 1.3 - Corpus Christi Edition: based on release 0.10.1 of Kaffe, featuring bugfixes, simplifications, new examples (from the tutorial) and a benchmarking program. Released on 13jun1998.
  • patch 1: fixes a problem in Kaffe that might cause it to crash when processing JNI calls or delivering intercepted non-static method invocations. Released on 14jun1998.

• 1.2 - Brazilian Slavery Abolition Day Edition: based on the May 12's snapshot of Kaffe. It was very thoroughly tested, so except this release to be a very stable one. And with great performance improvements! Released on 13may1998.
  • patch 1: fixes some endianness problems that affected only the sparc port. It would prevent almost any operation replacement. Released on 19may1998.
  • patch 2: selects correct wrapper classes for returning non-Object types from java.lang.reflect.Method.invoke. Released on 26may1998.

• 1.1 - Easter Edition: several serious bug-fixes and some improvements. Still based on Kaffe 0.9.2; if you can't find it elsewhere, please move to a newer release, since the package javasoft.com needed by that version of Kaffe cannot be legally distributed. Released on 13apr1998.

• 1.0 - Carnival Edition: an 86 Kb gzipped tar file containing Java source code, some glue patches for Kaffe 0.9.2 and a new Kaffe package. Released on 25feb1998.

Related Work

A list of Java-based reflective architectures are listed below. This list should probably be expanded to include other reflective architectures, based on other programming languages, as well as other open architecture efforts.

• OpenJava is a Java source-code pre-processor that requires base-level code to be modified so as to add `metaobject' declarations, mostly like in OpenC++. Only classes whose source code can be modified can be made reflective.
• R-Java extends the Guavac compiler and the Kaffe OpenVM to introduce Shells, an (overly?) simplified kind of meta-object that can be attached at run-time to instances of classes specified at compile-time, overriding certain methods of the base-level class.
• Java// preprocesses Java class-files in order to generate derived classes with interception abilities. Therefore, only non-static non-private methods of non-final classes can be intercepted.
• Dalang preprocesses class-files at class loading time, through the definition of ClassLoaders, implicitly creating one interceptor meta-object for each object.
• MetaXa (formerly known as MetaJava) is a Java interpreter with interception abilities similar to those of Guaraná, but with a much weaker composition mechanism.
• Reflective Java: as far as I know, there is not much information publicly available about this project. A paper about it was presented at the OOPSLA'98 Workshop on Reflective Programming in C++ and Java.

Why not 100% Pure Java?

• Preprocessing bytecodes and translating them dynamically takes quite a lot of time. Even more so if you take into account that a bytecode verifier would have to be run before translating the class.
• Code must be added to test whether operations must be intercepted or not, and this would make the code run much slower if it were implemented in the bytecode level.
• Classes loaded with a ClassLoader cannot have native methods and, even if they could, it would not be possible to intercept their invocations in the general case, for example, when a native method invokes another.
• Classes from the CLASSPATH, and particularly from the Java API, cannot be reloaded or modified with ClassLoaders.
• Some classes from the Java API would have to be modified or even replaced in order to hide the additional code that would certainly have to be introduced in order to support interception.
• It is impossible to intercept constructor invocations without violating security constraints of Java bytecode.
• Because some code must be added to allow for interception of operations, it may be impossible to translate large methods, that get close to internal limitations of the Java VM, in terms of code size, number of stack slots or of local variables, or even constant pool size. Such large methods and classes are not generally developed manually, but by automatic code generators.

Mailing List

This project might not have been possible without the financial support provided by FAPESP, that has provided scholarships for individual students and equipment for the Laboratory of Distributed Systems. We have also had support from CNPq.

Unrelated Work

Matthew and Bernard Duggan, other fans of guaraná, that own guarana.org, were also very kind in maintaining a link to this web page and an e-mail address @guarana.org. Thank you all, folks!

For some botanical information about Guaraná, see this. Thanks to Mike Corbeil for the URL.