javaobj 0.1 → 0.2

data/lib/javaobs.rb

@@ -1,11 +1,60 @@
  
 require 'delegate'
 
+# Java Objects namespace to read and write Java serialized objects to streams. 
+# Any Java serialized object can be read from a stream. To write a Java object,
+# the meta class must be primed with a sample input serialized object. The is 
+# required because Java uses a UUID to identify classes and it is generated using
+# a complex hashing scheme of data and method signatures. Since this system does
+# not have access to that information, it needs to get it from a serialized object.
+#
+# Objects that have custom serialization methods can be read and written by 
+# creating a class as we have for the Date class:
+#
+#   class Date < SimpleDelegator
+#     extend JavaObject
+#  
+#     def initialize
+#      super(Time)
+#     end
+#  
+#     def time=(time)
+#       case time
+#       when Time
+#         __setobj__(time)
+#       
+#       when String
+#         t, = time.unpack("Q")
+#         __setobj__(Time.at(t / 1000, (t % 1000) * 1000))
+#       end
+#     end
+#
+#     def data
+#       t = __getobj__.tv_sec * 1000 + __getobj__.tv_usec / 1000
+#       [t].pack("Q")
+#     end
+#   end
+#
+# The important methods are the data method that is used for writing the 
+# the object to a stream.
+#
+# All other classes will be auto-generated when the stream is read and persisted. 
+# A Java Meta Class is added to the Ruby Class that contains all the Java field
+# information needed to serialize the objects. 
+
 module Java
+  
+  # An error thrown when a serialization error occurs.
+  class SerializationError < RuntimeError
+  end
+  
+  # An representation of a Java instance variable used to serialize
+  # data to and from a stream.
   class JavaField
     attr_reader :name, :type
     attr_accessor :subtype
     
+    # Create a java instance variable with a name and data type.
     def initialize(name, type)
       @name = name
       @type = type
@@ -17,6 +66,9 @@ module Java
     end
   end
   
+  # The Java meta class with all the information needed for 
+  # serialization of the Ruby class to the stream. This class
+  # is attached to the Ruby class.
   class JavaClass
     attr_accessor :superClass, :rubyClass
     attr_reader :name, :uid, :fields, :javaName, :flags, :arrayType
@@ -31,6 +83,7 @@ module Java
       @arrayType = name[1] if name[0] == ?[
     end
       
+    # Add a field to the class.
     def addField(field)
       @fields << field
     end
@@ -40,19 +93,24 @@ module Java
     end
   end
   
+  # A small mixin to extend a Ruby class with the associated
+  # JavaClass.
   module JavaObject
     def javaClass
       @javaClass
     end
   end
   
+  # The custom serialization of the Java Date class
   class Date < SimpleDelegator
     extend JavaObject
     
     def initialize
       super(Time)
     end
-    
+
+    # Set the time with a Time object or a Java binary serialized
+    # date.
     def time=(time)
       case time
       when Time
@@ -64,16 +122,19 @@ module Java
       end
     end
 
+    # Get the data in the form needed for the Java date serialization.
     def data
       t = __getobj__.tv_sec * 1000 + __getobj__.tv_usec / 1000
       [t].pack("Q")
     end
   end
 
+  # The Java Array wrapper using an Ruby Array.
   class JavaArray < Array
     extend JavaObject
   end
 
+  # Container for the Java serialization constants.
   module ObjectStream
     STREAM_MAGIC = 0xACED
     STREAM_VERSION = 5
@@ -111,6 +172,8 @@ module Java
     PRIM_OBJECT  = 76 # 'L'
   end
   
+  # The Ruby version of the Java ObjectInputStream. Creates a Ruby 
+  # proxy class for each Java Class.
   class ObjectInputStream
     include ObjectStream
     
@@ -125,6 +188,7 @@ module Java
     def readUID; @str.read(8); end
     def readLong; @str.read(8).unpack("Q").first; end
     
+    # Read a Java block of data with a size and then the following data.
     def readBlockData
       byte = readByte
       size = nil
@@ -136,15 +200,16 @@ module Java
         size = readInt
         
       else
-        raise "Expecting TC_BLOCKDATA" unless byte == TC_BLOCKDATA
+        raise SerializationError, "Expecting TC_BLOCKDATA" unless byte == TC_BLOCKDATA
       end
       
       data = @str.read(size)
       byte = readByte
-      raise "Unexpected byte #{byte}" unless byte == TC_ENDBLOCKDATA
+      raise SerializationError, "Unexpected byte #{byte}" unless byte == TC_ENDBLOCKDATA
       data
     end
     
+    # Read all the fields from the stream and add them to the class.
     def readFields(klass)
       fieldCount = readShort
       1.upto(fieldCount) do
@@ -160,11 +225,14 @@ module Java
       end
     end
     
+    # Read the class annotation. We do not currently handle annotations.
     def readClassAnnotation
       ebd = readByte
-      raise "We do not handle annotations!" unless ebd == TC_ENDBLOCKDATA
+      raise SerializationError, "We do not handle annotations!" unless ebd == TC_ENDBLOCKDATA
     end
     
+    # Read the Java class description and create a Ruby class to proxy it 
+    # in this name-space. Added special handling for the Date class.
     def readClassDesc
       name = readString
       uid = readUID
@@ -215,6 +283,7 @@ module Java
       klass
     end
 
+    # Read an array of objects.
     def readArray(klass)
       size = readInt
       a = klass.rubyClass.new
@@ -225,6 +294,7 @@ module Java
       a
     end
 
+    # Read a primitive data type.
     def readType(type, arrayType = nil, field = nil)
       case type
       when PRIM_BYTE
@@ -255,10 +325,11 @@ module Java
         readObject
         
       else
-        raise "Unknown type #{type}"
+        raise SerializationError, "Unknown type #{type}"
       end
     end
 
+    # Read class data and recursively read parent classes.
     def readClassData(klass, object = nil)
       # Handle special case for Date
       if object == nil
@@ -285,6 +356,7 @@ module Java
       object
     end
     
+    # Read an object from the stream.
     def readObject
       object = nil
       byte = readByte
@@ -313,12 +385,13 @@ module Java
         object = nil
         
       else
-        raise "Unexpected byte #{byte} at #{@str.pos}"
+        raise SerializationError, "Unexpected byte #{byte} at #{@str.pos}"
       end
 
       object
     end
 
+    # Initialize from a stream.
     def initialize(str)
       @str = str
       magic =  readUShort
@@ -330,6 +403,8 @@ module Java
 
     end
 
+    # Read all objects in the stream. Calls readObject until the stream
+    # eof is reached.
     def readObjects
       objs = []
       until (@str.eof)
@@ -339,6 +414,8 @@ module Java
     end
   end
 
+  # A Ruby version of the Java ObjectOutputStream. The Ruby classes must 
+  # have attached Java meta classes to attach UUID.
   class ObjectOutputStream
     include ObjectStream
 
@@ -353,99 +430,108 @@ module Java
     def writeUID(u); @str.write u; end
     def writeLong(l); @str.write [l].pack("Q"); end
 
-   def nextHandle
-     h = @nextHandle
-     @nextHandle += 1
-     h
-   end
-   
-   def writeArray(klass, v)
-     type = klass.arrayType
-     writeInt(v.length)
-     v.each do |e|
-       writeType(type, e)
-     end
-   end
-   
-   def writeBlockData(data)
-     if (data.length <= 255)
-       writeByte(TC_BLOCKDATA)
-       writeByte(data.length)
-     else
-       writeByte(TC_BLOCKDATALONG)
-       writeInt(data.length)
-     end
+    # Creates object reference handles.
+    def nextHandle
+      h = @nextHandle
+      @nextHandle += 1
+      h
+    end
 
-     @str.write data
-     writeByte(TC_ENDBLOCKDATA)
-   end
+    # Write an array of objects.
+    def writeArray(klass, v)
+      type = klass.arrayType
+      writeInt(v.length)
+      v.each do |e|
+        writeType(type, e)
+      end
+    end
 
-   def writeType(type, v)
-     case type
-     when PRIM_BYTE
-       writeByte(v)
-       
-     when PRIM_CHAR
-       writeByte(v)
-       
-     when PRIM_DOUBLE
-       writeDouble(v)
-       
-     when PRIM_FLOAT
-       writeFloat(v)
-       
-     when PRIM_INT
-       writeInt(v)
-       
-     when PRIM_LONG
-       writeLong(v)
-       
-     when PRIM_SHORT
-       writeShort(v)
-       
-     when PRIM_BOOL
-       writeBool(v)
-       
-     when PRIM_OBJECT, PRIM_ARRAY
-       writeObject(v)
-       
-     else
-       raise "Unknown type #{type}"
-     end
-   end
-
-   def writeClassDesc(klass)
-     @handles[klass] = nextHandle
-     
-     writeString klass.javaName
-     writeUID klass.uid
-     writeByte klass.flags
-
-     writeShort(klass.fields.length)
-     klass.fields.each do |f|
-       writeByte(f.type)
-       writeString(f.name)
-       writeObject(f.subtype) if f.subtype
-     end
+    # Writes a block of data to the stream.
+    def writeBlockData(data)
+      if (data.length <= 255)
+        writeByte(TC_BLOCKDATA)
+        writeByte(data.length)
+      else
+        writeByte(TC_BLOCKDATALONG)
+        writeInt(data.length)
+      end
 
-     writeByte(TC_ENDBLOCKDATA) # Annotations
-     writeObject(klass.superClass)
-   end
-
-   def writeObjectData(klass, obj)
-     writeObjectData(klass.superClass, obj) if klass.superClass
-     
-     if klass.flags == SC_SERIALIZABLE
-       klass.fields.each do |f|
-         v = obj.send(f.name.intern)
-         writeType(f.type, v)
-       end
-     else
-       writeBlockData(obj.data)
-     end
-   end
+      @str.write data
+      writeByte(TC_ENDBLOCKDATA)
+    end
+
+    # Reads a Java primitive type.
+    def writeType(type, v)
+      case type
+      when PRIM_BYTE
+        writeByte(v)
+
+      when PRIM_CHAR
+        writeByte(v)
+
+      when PRIM_DOUBLE
+        writeDouble(v)
+
+      when PRIM_FLOAT
+        writeFloat(v)
+
+      when PRIM_INT
+        writeInt(v)
+
+      when PRIM_LONG
+        writeLong(v)
+
+      when PRIM_SHORT
+        writeShort(v)
+
+      when PRIM_BOOL
+        writeBool(v)
+
+      when PRIM_OBJECT, PRIM_ARRAY
+        writeObject(v)
+
+      else
+        raise SerializationError, "Unknown type #{type}"
+      end
+    end
+    
+    # Writes the class description to the stream.
+    def writeClassDesc(klass)
+      @handles[klass] = nextHandle
+
+      writeString klass.javaName
+      writeUID klass.uid
+      writeByte klass.flags
+
+      writeShort(klass.fields.length)
+      klass.fields.each do |f|
+        writeByte(f.type)
+        writeString(f.name)
+        writeObject(f.subtype) if f.subtype
+      end
+
+      writeByte(TC_ENDBLOCKDATA) # Annotations
+      writeObject(klass.superClass)
+    end
+
+    # Write the object and class to the stream.
+    def writeObjectData(klass, obj)
+      writeObjectData(klass.superClass, obj) if klass.superClass
+
+      if klass.flags == SC_SERIALIZABLE
+        klass.fields.each do |f|
+          v = obj.send(f.name.intern)
+          writeType(f.type, v)
+        end
+      else
+        writeBlockData(obj.data)
+      end
+    end
    
-   def writeObject(obj)
+    # Writes the object and class data to the stream. Will 
+    # write a reference if the object has already been written 
+    # once.
+    def writeObject(obj)
      unless obj
        writeByte(TC_NULL)
      else
@@ -465,38 +551,39 @@ module Java
            writeObject(obj.class.javaClass)
            writeArray(obj.class.javaClass, obj)
            @handles[obj] = nextHandle
-           
+       
          when String
            writeByte(TC_STRING)
            writeString(obj)
            @handles[obj] = nextHandle
-           
+       
          else
            writeByte(TC_OBJECT)
            klass = obj.class.javaClass
            writeObject(klass)
            @handles[obj] = nextHandle
            writeObjectData(klass, obj)
-           
          end
        end
      end
-   end
+    end
 
-   def writeObjects(objs)
-     objs.each do |o|
-       writeObject o
-     end
-   end
-   
-   def initialize(str)
-     @str = str
-     @handles = {}
-     @nextHandle = 0
-     
-     writeUShort(STREAM_MAGIC)
-     writeShort(STREAM_VERSION)
-   end
+    # Write an array of objects to the stream.
+    def writeObjects(objs)
+      objs.each do |o|
+        writeObject o
+      end
+    end
+
+    # Create an o writer on with a stream.
+    def initialize(str)
+      @str = str
+      @handles = {}
+      @nextHandle = 0
+
+      writeUShort(STREAM_MAGIC)
+      writeShort(STREAM_VERSION)
+    end
   end
 end
 

data/rakefile

@@ -6,9 +6,9 @@ require 'rake/packagetask'
 require 'rake/gempackagetask'
 require 'rake/contrib/rubyforgepublisher'
 
-PKG_BUILD     = '1'
+PKG_BUILD     = '2'
 PKG_NAME      = 'javaobj'
-PKG_VERSION   = '0.1'
+PKG_VERSION   = '0.2'
 PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
 
 RELEASE_NAME  = "REL #{PKG_VERSION}"
@@ -27,9 +27,10 @@ end
 Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_dir = 'doc'
   rdoc.title    = "Java Objects"
+  rdoc.main = 'README.rdoc'
   rdoc.options << '--line-numbers' << '--inline-source'
   rdoc.template = "#{ENV['template']}.rb" if ENV['template']
-  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.include('README.rdoc', 'lib/**/*.rb')
 end
   
 dist_dirs = [ "lib", "test", "examples" ]

metadata

@@ -3,7 +3,7 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: javaobj
 version: !ruby/object:Gem::Version 
-  version: "0.1"
+  version: "0.2"
 date: 2006-04-16 00:00:00 -07:00
 summary: Decode Java Serialized Objects to Ruby Objects.
 require_paths: