Jallie User Manual

Introduction

JALLIE is a tool that can be used to disassemble, explore, update, and write to the Java class file format. It has a few batch-mode options for disassembling or running scripts over class files, but its most powerful usage is running in interactive mode with the class file loaded into memory. In this mode, you have a python command prompt and full access to all of python, and the class is parsed and loaded into specialized data structures that make exploring, dumping, or changing the classfile data safe and easy. In this mode you're really running a glorified binary editor which can take care of much of the class file bookkeeping for you.

Getting Started

Disassembling Class Files

The most straightforward way to view your class files is to simply disassemble them. You can do this in jallie in batch mode in which case it will disassemble all files listed on the command-line and print them out in excruciating detail (right down to the fields of the bytecodes). Files can be listed as relative or absolute paths, or you can provide the dotted-package name format (like you would for java or javah). When disassembly has completed the program will exit.

user@home> ./jallie --dis Hello.class 2>/dev/null
ClassFile  {
  u4 magic = 0xcafebabe
  u2 minor_version = 0
  u2 major_version = 50
  u2 constant_pool_count = 29
  cp_info constant_pool[29] {
    [ 0 ] [Unused]
    [ 1 ] CONSTANT_Methodref_info  {
      u1 tag = 10
      u2 class_index = #6 // "java/lang/Object"
      u2 name_and_type_index = #15 // <init> ()V
    }
    [ 2 ] CONSTANT_Fieldref_info  {
      u1 tag = 9
      u2 class_index = #16 // "java/lang/System"
      u2 name_and_type_index = #17 // out Ljava/io/PrintStream;
    }                                                                           

user@home>
    

Exploring Class Files

The common use of the program is to explore class file interactively by starting with an overview and drilling down to the points of interest. This is the default mode of the application. You can either preload a number of classes by providing the class file locations (or class names), or you can load files from inside the environment. Classes that are automatically loaded will be assigned to a python variable which matches the class name. A variable loaded also exists which is a list that contains all the auto-loaded classfiles. Classfiles which are loaded interactively are not assigned variables nor do they get added to the loaded variable (but you can do these things if you want to).

Automatically-loaded classes which are in the default package will be assigned to simple name variables which match the class name. Classes which are in packages will be accessible through their full dotted-package name.

user@home> ./jallie Hello.class com/foo/Main.class
Loaded class: "Hello"
Loaded class: "com/foo/Main"
>>> print loaded
[ ClassFile(Hello), ClassFile(com/foo/Main) ]
>>> print com.foo.Main
ClassFile  {
  u4 magic = 0xcafebabe
  u2 minor_version = 0
  u2 major_version = 50
  u2 constant_pool_count = 29
  cp_info constant_pool[29] = { ... }
  u2 access_flags = ( ACC_PUBLIC, ACC_SUPER )
  u2 this_class = #5 // "com/foo/Main"
  u2 super_class = #6 // "java/lang/Object"
  u2 interfaces_count = 0
  u2 interfaces[0] = { ... }
  u2 fields_count = 0
  field_info fields[0] = { ... }
  u2 methods_count = 2
  method_info methods[2] = { ... }
  u2 attributes_count = 1
  attribute_info attributes[1] = { ... }
}
    

Classes can also be loaded from a specific file on-the-fly, or empty classes can be created:

>>> cf = ClassFile('Goodbye.class')
>>> print cf.access_flags
33
>>> empty = ClassFile()
>>> print empty
ClassFile  {
  u4 magic = 0xcafebabe
  u2 minor_version = 0
  u2 major_version = 0
  u2 constant_pool_count = 1
  cp_info constant_pool[1] = { ... }
  u2 access_flags = (  )
  u2 this_class = #0 // NULL
  u2 super_class = #0 // NULL
  u2 interfaces_count = 0
  u2 interfaces[0] = { ... }
  u2 fields_count = 0
  field_info fields[0] = { ... }
  u2 methods_count = 0
  method_info methods[0] = { ... }
  u2 attributes_count = 0
  attribute_info attributes[0] = { ... }
}
>>>

    

Modifying the Class Files

Changing a primitive values is usually as simple as typing in the assignment statement.

>>> print Hello.major_version
50
>>> Hello.major_version = 49
>>> Hello.minor_version = 3
>>> print Hello
ClassFile  {
  u4 magic = 0xcafebabe
  u2 minor_version = 3
  u2 major_version = 49
  u2 constant_pool_count = 29
  cp_info constant_pool[29] = { ... }
  u2 access_flags = ( ACC_PUBLIC, ACC_SUPER )
  u2 this_class = #5 // "Hello"
  u2 super_class = #6 // "java/lang/Object"
  u2 interfaces_count = 0
  u2 interfaces[0] = { ... }
  u2 fields_count = 0
  field_info fields[0] = { ... }
  u2 methods_count = 2
  method_info methods[2] = { ... }
  u2 attributes_count = 1
  attribute_info attributes[1] = { ... }
}
>>>
    

For access flags, the ACC_<flag> variables are defined and can be used to set the access flag bitfields. Use the or, and, or not bit operations to set the appropriate fields. There are similar type definitions for the T_<type> constants used in the newarray instruction.

>>> print ACC_PROTECTED
4
>>> Hello.access_flags = ACC_SUPER | ACC_PROTECTED
>>> print Hello.access_flags
36
>>> print Hello
ClassFile  {
  u4 magic = 0xcafebabe
  u2 minor_version = 3
  u2 major_version = 49
  u2 constant_pool_count = 29
  cp_info constant_pool[29] = { ... }
  u2 access_flags = ( ACC_PROTECTED, ACC_SUPER )
  u2 this_class = #5 // "Hello"
  u2 super_class = #6 // "java/lang/Object"
  u2 interfaces_count = 0
  u2 interfaces[0] = { ... }
  u2 fields_count = 0
  field_info fields[0] = { ... }
  u2 methods_count = 2
  method_info methods[2] = { ... }
  u2 attributes_count = 1
  attribute_info attributes[1] = { ... }
}
>>>
    

Some fields it does not make sense to change, such as the Java signature (the magic field). Also, there are many instances in the classfile where a length field deliniates the length of the following array. The is crucial in reading in the array, but once loaded the arrays are represented as python lists which have an implicit length. For this reason, the data structure mechanisms simply use the array length to update the length field dynamically so there's no need to change the field yourself. Change the array instead and the field will be automatically updated. This is enforced if you try to write to an automatically-set length field (this goes for attribute lengths as well).

>>> Hello.magic = 0x8badbeef
Error performing assignment: Field is read-only
>>> Hello.constant_pool_count = 10
Error performing assignment: Field is a length field (change the array instead)
>>> Hello.interfaces_count = 4
Error performing assignment: Field is a length field (change the array instead)
>>> Hello.interfaces += [ 4, 5, 6, 7 ]
>>> print Hello.interfaces_count
4
    

Similarly, some fields are discriminator values which determine the type of the structure in arrays which have variable-typed contents. The tag field in cp_info, for instance is an instance of this. Since the actual data associated with the structure is the type, the tag value is redundant after the data has been parsed. It is displayed for completeness, but is read-only. If you want a different discriminator value, replace the entire array entry with the new type, rather than trying to change the value.

>>> print Hello.constant_pool[9]
CONSTANT_Utf8_info  {
  u1 tag = 1
  u2 length = 4
  u1 bytes[] = "Code"
}
>>> Hello.constant_pool[9].tag = 7
Error performing assignment: Can't change cp_info tag
>>> Hello.constant_pool[9] = CONSTANT_Class_info()
>>> print Hello.constant_pool[9]
CONSTANT_Class_info  {
  u1 tag = 7
  u2 name_index = #0 // NULL
}
    

When making changes to bytecode which change the size, jallie attempts to adjust the affected code offsets in the classfile, such as the inter-code bci offsets in branch instructions, the exception handler table, and the LocalVariableTable, LocalVariableTypeTable, LineNumberTable, and StackMapTable. It would be wise to second-check these values after modifying bytecode to ensure they were adjusted correctly.

Saving Classes

Once you've made modifications to the classfile, you can write the modified bytes back to a classfile for later use using the write() method. You can write to the default file name, or specify a specific file to write to. If no extension is given, a '.class' extension is assumed.

>>> Hello.write()
Wrote 481 bytes to file 'Hello.class'
>>> Hello.major_version = 49
>>> Hello.minor_version = 3
>>> Hello.write('Hello_v49')
Wrote 481 bytes to file 'Hello_v49.class'
>>> Hello.write('bytes.bin')
Wrote 481 bytes to file 'bytes.bin'
    

Settings

There are a few user-controlable settings that can be used to change the default behavior. These settings are contained in the Settings class and can be assigned to at any time.

For example:

>>> Settings.extraDetailLevels=2
>>> Settings.indent='"""'
>>> print Hello.methods[1]
method_info  {
"""u2 access_flags = ( ACC_PUBLIC, ACC_STATIC )
"""u2 name_index = #11 // "main"
"""u2 descriptor_index = #12 // "([Ljava/lang/String;)V"
"""u2 attributes_count = 1
"""attribute_info attributes[1] {
""""""[ 0 ] attribute_info  {
"""""""""u2 attribute_name_index = #9 // "Code"
"""""""""u4 attribute_length = 37
"""""""""u2 max_stack = 2
"""""""""u2 max_locals = 1
"""""""""u4 code_length = 9
"""""""""bytecode code[4] = { ... }
"""""""""u2 exception_table_length = 0
"""""""""exception_table_entry exception_table[0] = { ... }
"""""""""u2 attributes_count = 1
"""""""""attribute_info attributes[1] = { ... }
""""""}
"""}
}
    

Scripting

Jallie can also be used to bulk-process classfiles. This can be used for summarizing, searching, or algorithmically modifying classfiles. To use the processing capability, create a module with a global method named for_ClassFile which takes two arguments, a ClassFile object, and an optional pass-in command-line parameter. When the module name is passed to the --processor flag, instead of entering interactive mode, jallie will parse each classfile in it's command-list and call the for_ClassFile method with each classfile as an argument. If a --processor_arg value is specified on the command line, that is passed as the scond argument to for_ClassFile For example:

> cat version.py

def for_ClassFile(cf, arg):
  print '%s %s: %d.%d: num methods: %d' % \
    ( arg, cf.classname(), cf.major_version, cf.minor_version, len(cf.methods) )

> jallie -q --processor=version --processor_arg=asdf Hello LockExample 2>/dev/null
asdf Hello: 51.0: num methods: 2
asdf LockExample: 49.0: num methods: 4