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.
Guaraná (pronounced gwadda-naa, with American
accent; also known as Guarana, for the ISO-8859-1 challenged :-)
is a reflective architecture that aims at simplicity, flexibility,
security and reuse of meta-level code. It features a run-time
meta-object protocol that provides for easy composition of
meta-objects and allows for dynamic reconfiguration. If you're
not familiar with reflection and meta-objects, you may want to
The first picture on the right was taken just after my MSc
presentation, in August, 1998. Everybody was obviously drinking
guaraná. :-) The ones on the left are my parents; in the center is
Professor Luiz Eduardo Buzato, my advisor. Islene, my fiancée, is
just in front of me. My aunt, Sofia, is the one behind the
(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.
(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
Reflective Programming in C++ and Java.
Gutknecht (in the third picture on the right), that created
the Oberon system
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
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
Collegiate Programming Contest.
The Guaraná API: Produced by pizzadoc
from the Guaraná 1.7 source files.
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
IC-98-33. Accepted for presentation at the OOPSLA'98
Reflective Programming in C++ and Java.
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
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
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
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
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
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
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 :-(
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.
interception: an experimental patch described here.
To avoid having to rebuild
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
interception of field operations requested through
java.lang.reflect.Field was utterly broken, due
to changes in the last release. Released on 13jun1999.
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.
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
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
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 :-(.
the Kaffe 1.0.b2 branch would garbage collect meta-objects
even if they are still associated with base-level objects.
Released on 21nov1998.
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! :-)
allows the creation of field write operations through
operation factories. Fixed on 12feb1998, released on
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.
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.
fixes some endianness problems that affected only the
sparc port. It would prevent almost any operation
replacement. Released on 19may1998.
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.
Guaraná Development Kit, is a toolkit to ease the development of
reflective applications, introducing higher-level components that
build upon the MOP of Guaraná. dejavu, a debugging and
reverse-engineering tool built with Guaraná and GDK, is available
at the same web-page.
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.
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
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
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
Reflective Programming in C++ and Java.
We have decided to modify the Kaffe OpenVM, instead of dynamically
modifying Java bytecodes through ClassLoader
preprocessing because this dynamic modification is likely to lead
to poor performance and arbitrary limitations in reflective
abilities. There are several issues involved:
Add to this the fact that Kaffe OpenVM is the most portable
existing Java Virtual Machine, JIT compilation is available on
most of the supported platforms, and it is Free Software, and
you'll understand why we decided to modify it instead of trying a
limited 100% Pure Java implementation... :-)
Anyway, we haven't yet discarded the possibility of implementing
the reflective architecture of Guaraná with dynamic translation of
bytecodes. Even though some operations just can't be intercepted,
and some classes can't be made reflective, it might be interesting
to compare the performance and the limitations of this
implementation with the one we already have. Some nice starting
points would be Soot, a set of tools
for Java bytecode generation and processing and GNU
bytecode, part of the Kawa
Java-based Scheme interpreter.
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
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
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
A mailing list has been set up for discussing Guaraná: the
reflective architecture, its implementation and applications. To
subscribe, send an empty e-mail to
firstname.lastname@example.org, or browse the
Guaraná was created as my Master Thesis
project, with a lot of help from my advisor (Luiz Eduardo Buzato,
PhD) and my wife (Islene Calciolari
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
Guaraná (Paullinia cupana) is the name of an Amazonian
fruit that contains guaranine, a substance very similar with
caffeine, but much more powerful. You may find a lot of
information about the fruit and the soda at www.guarana.com. Hans van
Rijsse, who maintains that site, has been nice enough to provide
me with an e-mail address @guarana.com.
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,
For some botanical information about Guaraná, see this. Thanks to
Mike Corbeil for the URL.
If you have any suggestions, comments or questions, feel free to
send e-mail to
Alexandre Oliva. This is not an official publication of
IC-Unicamp nor Unicamp, and the opinions expressed here do not
necessarily represent the opinions of the University.
This page is
Best Viewed With Any Browser
Last modified: 2004-03-20