Matt McCutchen's Web SiteMirror  (Top, Reflection, What is Mirror?, Launching Mirror, Getting started, How the windows work, The control center, Bottom).  Email me about this page.

Mirror

Mirror icon

Mirror is a Java applet I wrote on my own.  It uses Java's reflection to present an interactive view of classes and their parts.  If your browser has Java, click the button below to launch it and start playing around.  It will come up with a Welcome screen with some documentation.  A slightly revised version of the documentation is below.

Mirror was written and (I believe) compiled for Java 1.4.2, but I've been using Java 1.5 tools recently; please tell me if I've made a mistake and it doesn't run on Java 1.4.2.  Unfortunately, Mirror has not been updated for the new language features in Java 1.5, so its own interface does not show generics and so forth.  What you can do is use Mirror to access the new Java 1.5 reflection classes.

Mirror is available for download in the form of a jar file containing the source code and the compiled code.  It is really a Zip file with a different extension, so you can look inside with any Zip tool.  But be cautioned that, since the files inside must be accessible to Java, I couldn't put everything in one nicely-named folder like people do these days; make yourself such a folder before extracting the file.  You can launch Mirror from this file in any of the ways described in the Mirror documentation; the simplest is to type java -jar mirror-XXXX.XX.XX at the command line.

In version 2005.07.20, I made minor improvements.  Mirror now has a button to recover objects you have named but to which you have lost all references, and it doesn't forget about all the presenters if you quit and relaunch it.

DescriptionFileSizeModification time
Mirror version 2005.07.20mirror-2005.07.20.jar1789612005-07-20 14:41:44 +0000

And here is the Mirror documentation.

Reflection

Java's reflection mechanism allows Java programs to obtain information about the structure and capabilities of classes, constructors, methods, and fields at runtime.  Programs can use program elements that they discover through reflection.  For example, one could write a program that accepts a class name from the user, obtains a list of its methods through reflection, and invokes a random no-argument method.

What is Mirror?

Using Mirror, you can explore classes in the standard Java library or any others in your classpath.  You can make new objects, run constructors and methods, and access fields.  Mirror uses reflection to perform your requests.

By itself, Mirror is a new, compelling way to interact with and learn about Java.  It can also be used to investigate objects created by other Java programs (primarily for debugging purposes, although there are many other tools better suited for this) or to test a Java library that has no user interface.

Launching Mirror

There are many different ways to launch Mirror.  Which one you should use depends on what classes you want to investigate with Mirror.

  1. Run mirror.jar directly:
    java -jar mirror.jar
    The -jar option causes the JVM to ignore any classpath specified in the environment.  It looks for classes only in the standard library and in the Jar file you specify.  As a result, you will only be able to access the standard library (and the classes that make up Mirror itself).  In Mac OS X, double-clicking a Jar file does essentially this.  The instance of Mirror you may have launched with the button above runs in this mode.
  2. Run the main class hashproduct.mirror.MirrorMain, providing mirror.jar and other folders or Jars to the JVM as sources of classes:
    java -cp mirror.jar:(others) hashproduct.mirror.MirrorMain
    Replace (others) by a classpath for the classes you want to access with Mirror.  You can reference your CLASSPATH variable here if you like.
  3. Add mirror.jar and the classes you want to access to your CLASSPATH environment variable.  (This is convenient, but it takes a bit of work to set up.)  Then you need only type:
    java hashproduct.mirror.MirrorMain
  4. If you are using an IDE (such as Metrowerks CodeWarrior), add mirror.jar to your project and set the main class to hashproduct.mirror.MirrorMain.  When you run the project, Mirror will open and you can access all the classes in the project.
  5. Open hashproduct.mirror.MirrorApplet as an applet.  I probably should have included an HTML page referencing the applet for convenience; well, you have this page.
  6. Mirror can be launched by other Java programs that want to be reflected upon.  To find out how, take a look at the source code, or talk to me.

Getting started

You might start by opening a class using the box at the bottom of the control center.  Type the name, including the package, in the box and click "Open class".  Take a look at the information that Mirror provides about its constructors, methods, and fields on their respective tabs.  If you've never used Java before, you might find these classes interesting:

Then, try constructing an object.  To do so, open a constructor from the "Constructors" tab.  Go to the "Invoke" tab, fill in any arguments, and hit "Invoke".  A window will appear, presenting you with the constructed object.  You can open it and call a method from the "Methods" tab; the procedure is similar.

How the windows work

A typical Mirror window (a ReflectorFrame in the source code) represents a class, constructor, method or field and may or may not carry a calling object of an appropriate type (look for the "Calling object" tab).  When Mirror wants to show you an object, it simply opens a class window carrying that object, but it sets a flag so that the window title is the object name.  (This is the object's identityHashCode unless you give it a custom name.)  In all other cases, the window title is the name of the class, etc.

Whenever you use one Mirror window to open another, the new window gets the same calling object (if that object is of an appropriate type).  To invoke a method on or access a field of a particular object, you must get a window representing that method or field and carrying the desired object; usually, this means opening the method or field from a class window carrying that object.

You also get a window (a CallFrame) for each constructor and method invocation.  The window appears when you hit "Invoke" and will present you with a return value, a constructed object, or a Throwable when the call completes.  Each call runs in its own thread so you can keep using Mirror while one is in progress.

The control center

You can hold references to objects you have created in the reflector bank on the control center.  Actually, you can hold Reflectors, which are combinations of a program element (class, constructor, method, field) and optionally a calling object; each ReflectorFrame represents one.  To deposit a reference, go to the object window and click "Grab".  Then click "Add held" on the control center.  The notion of "grabbing" serves as Mirror's object clipboard, and the box at the top of the control center shows what you are "holding".

The control center has a calculator that operates on primitive values with strict Java semantics.  It is a postfix calculator, so you must push values onto the stack (by clicking the appropriate "Push" buttons) before you can operate on them.


Matt McCutchen's Web SiteMirror  (Top, Reflection, What is Mirror?, Launching Mirror, Getting started, How the windows work, The control center, Bottom).  Email me about this page.
Modification time of this page's main source file: 2009-05-06 04:16:51 +0000
Except where otherwise noted, Matt McCutchen waives his copyright to the content of this site.  This site comes with absolutely no warranty.  Why?