NAME
    Java::JVM::Classfile - Parse JVM Classfiles

SYNOPSIS
      use Java::JVM::Classfile;

      my $c = Java::JVM::Classfile->new("HelloWorld.class");
      print "Class: " . $c->class . "\n";
      print "Methods: " . scalar(@{$c->methods}) . "\n";

DESCRIPTION
    The Java Virtual Machine (JVM) is an abstract machine which processes
    JVM classfiles. Such classfiles contain, broadly speaking,
    representations of the Java methods and member fields forming the
    definition of a single class, information to support the exception
    mechanism and a system for representing additional class attributes. The
    JVM itself exists primarily to load and link classfiles into the running
    machine on demand (performed by the Class Loader), represent those
    classes internally by means of a number of runtime data structures and
    facilitate execution (a role shared between the Execution Engine (which
    is responsible for execution of JVM instructions) and the Native Method
    Interface which allows a Java program to execute non-Java code,
    generally ANSI C/C++.

    This Perl module reveals the information in a highly-compressed JVM
    classfile by representing the information as a series of objects. It is
    hoped that this module will eventually lead to a JVM implementation in
    Perl (or Parrot), or possibly a way-ahead-of-time (WAT) to Perl (or
    Parrot) compiler for Java.

    It is important to remember that the Java classfile is
    highly-compressed. Classfiles are intended to be as small as possible as
    they are often sent across the network. This may explain the slightly
    odd object tree. One of the most important things to consider is the
    idea of a constant pool. All constants (constant strings, method names
    and signatures etc.) are clustered in the constant pool at the start of
    the classfile, and sprinkled throughout the file are references to the
    constant pool. The module attempts to hide this optimisation as much as
    possible from the user, however.

    It is probably important to at least have briefly read "The JavaTM
    Virtual Machine Specification", http://java.sun.com/docs/books/vmspec/

METHODS
  new

    This is the constructor, it takes the filename of the classfile to parse
    and returns an object:

      my $c = Java::JVM::Classfile->new("HelloWorld.class");

  magic

    This method returns the magic number for the classfile. All valid
    classfiles should have the magic number 0xCAFEBABE:

      my $magic = $c->magic;

  version

    This method returns the version of the classfile. The version consists
    of a major number and a minor number. For example, "45.3" has major
    number 45 and minor number 3:

      my $version = $c->version;

  class

    This method returns the name of the class that this classfile
    corresponds to:

      my $class = $c->class;

  superclass

    This method returns the name of the superclass of the class that this
    classfile corresponds to:

      my $superclass = $c->superclass;

  constant_pool

    This method returns the constant pool entries as an array reference.
    Each entry is an object. Currently undocumented.

      my $constant_pool = $c->constant_pool;

  access_flags

    This method returns the access flags for the class as an array
    reference. Possible flags are:

    abstract
        Declared abstract; may not be instantiated

    final
        Declared final; no subclasses allowed

    interface
        Is an interface, not a class

    public
        Declared public; may be accessed from outside its package

    super
        Treat superclass methods specially when invoked by the invokespecial
        instruction

      print "Flags: " . join(", ", @{$c->access_flags}) . "\n";

  interfaces

    This method returns an array reference of the interfaces defined in the
    classfile. Currently unimplemented:

      my $interfaces = $c->interfaces;

  fields

    This method returns an array reference of the fields defined in the
    classfile. Currently unimplemented:

      my $fields = $c->fields;

  methods

    This method returns an array reference of the methods defined in the
    classfile:

      my $methods = $c->methods;

    Each Java method is represented by an object which has the following
    methods: name, descriptor, access_flags and attributes. name and
    descriptor return the method name and descriptor. Possible access flags
    are:

    abstract
        Declared abstract; no implementation is provided

    final
        Declared final; may not be overridden

    native
        Declared native; implemented in a language other than Java

    private
        Declared private; accessible only within the defining class

    protected
        Declared protected; may be accessed within subclasses

    public
        Declared public; may be accessed from outside its package

    static
        Declared static

    strict
        Declared strictfp; floating-point mode is FP-strict

    synchronized
        Declared synchronized; invocation is wrapped in a monitor lock

    Various attributes are possible, the most common being the Code
    attribute, where the value holds information about the Java bytecode for
    the method:

      foreach my $method (@{$c->methods}) {
        print "  " . $method->name . " " . $method->descriptor;
        print "\n    ";
        print "is " . join(", ", @{$method->access_flags});
        print "\n    ";
        print "has attributes: ";
        foreach my $att (@{$method->attributes}) {
          my $name = $att->name;
          my $value = $att->value;
          if ($att->name eq 'Code') {
            print "      $name: ";
            print "stack(" . $value->max_stack . ")";
            print ", locals(" . $value->max_locals . ")\n";
            foreach my $instruction (@{$value->code}) {
              print $instruction->label . ':' if defined $instruction->label;
              print "\t" . $instruction->op . "\t" . (join ", ", @{$instruction->args}) . "\n";
            }
            print "\n";
            foreach my $att2 (@{$value->attributes}) {
              my $name2 = $att2->name;
              my $value2 = $att2->value;
              if ($name2 eq 'LineNumberTable') {
                print "\tLineNumberTable (offset, line)\n";
                print "\t" . $_->offset . ", " . $_->line . "\n" foreach (@$value2);
              } else {
                print "!\t$name2 = $value2\n";
              }
            }
          } else {
            print "!\t$name $value\n";
          }
        }
        print "\n";
      }

    Note that in the case of the Code attribute, the value contains an
    object which has three main methods: max_stack (the maximum depth of
    stack needed by the method), max_locals (the number of local variables
    used by the method), code (returns an arrayref of instruction objects
    which have op, args and label methods), and attributes. One attribute
    that Code can have is the LineNumberTable attributes, which has an
    arrayref of objects as a value. These have offset and line methods,
    representing a link between bytecode offset and sourcecode line.

  attributes

    This method returns an array reference of the attributes defined in the
    classfile. Attributes are common in many places in the classfile - here
    in particular we have the classfile attributes.

      my $attributes = $c->attributes;

    Attributes are represented by an object that has name and value methods:

      foreach my $attribute (@{$c->attributes}) {
        print "  " . $attribute->name . " = " . $attribute->value . "\n";
      }

    Possible attributes include the SourceFile attribute, the value of which
    is the source file that was compiled into this classfile.

BUGS
    A number of classfile features are not currently supported. This will be
    fixed real soon now.

    Not enough test programs.

AUTHOR
    Leon Brocard <acme@astray.com>

COPYRIGHT
    Copyright (C) 2001, Leon Brocard

    This module is free software; you can redistribute it or modify it under
    the same terms as Perl itself.