adb-sdklib 0.0.1 → 0.0.2

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    OTE3YzhiZDg1MzU4MzkxZGM1N2I5Y2IxYjIwYTgxNWQ1OWY0ZWU5NA==
+    ZGI1NWY1ZTRjNDdlNDFkOWU0YzNhODI4OWZlNjZhY2M5Mjg0ZTFiYQ==
   data.tar.gz: !binary |-
-    NmM3MzE5NmZhZjQxNmI0NjkyNjRkZWY4NGFkNzQwMmViMTA3NzJiOA==
+    YmQ4ZTg4NTI5MWVhYWQwOWRkMWY3NGVkOTgyYWIyNDMwZDhkMDI0Yg==
 SHA512:
   metadata.gz: !binary |-
-    YTY3ODE0OTI4MzI3Mzc4YTMwNzQ3ZmY4ZTQxMTZjNjQ0YzkxNTZlNzJmNzkz
-    NzZmM2QwYzU4NWMzN2U2MjY3MzU0ZGQwMDZhZjcyZWExMGQzNWY2YTM5MjU1
-    ZmIwZWQyZGQyNjA4YWRhNTMyOTMxZWUwYWRjZjdjOWU4MDNjNjY=
+    OWYzOTZjNDM2NDNmYzI0MmZiY2M1NTliYjY2OTkxZDkzMjYwOTk3NzUzNmI5
+    ZWI5ZjZiYzY4M2MwZTZmZjE4NzM5ZGMyYTA2YjM0MTZmODQyZTY3YjJhYTgy
+    YzEyNDg1OWIwMmU3YWE5MWUwOTRlOWJiZGNhZWMxNTA1N2YzMTg=
   data.tar.gz: !binary |-
-    MzFjYzhjYzUxNDRlNzdmOWNmNDZhODU1NzM5ZWQzN2Q5NTkzNTA0ZThjMzli
-    MzA1ZDU4ZTA3NGE0ZDA1MWVmMTRjNGNiOWM3MDg0NDY0ZGZmODAyYmQ1MzRj
-    NmU0YTc0NGZkYjQ2ODdkZjc0NzUxNWY5M2E5MDRhYjRhOGI0MDQ=
+    ZjlmZDA0YzVlMGI2NTdiMDAwMDA4ZjA5Y2U4NWQ5ZTRmYWYxOWMzZDUwODU1
+    ZWM0OGJjMzFmZTE1M2RmMjMxYzRjZmFlM2U4OTlkMmU1N2Q4NDcwZDMxNTYy
+    ODE2OWFlOGM2MjNhZTA3NWQ2NDhjNTMzNWI0NjZlZTg0ZGI4ZTg=

data/.yardopts

@@ -0,0 +1,5 @@
+--title 'AdbSdkLib Documentation'
+--no-private
+--main=README.md
+-
+README.md

data/README.md

@@ -14,19 +14,19 @@ $ gem install adb-sdklib
 
 ## Usage
 
-### Adb Object
+### *Adb* object
 
 ```ruby
 require 'adb-sdklib'
 adb = AdbSdkLib::Adb.new
 # If 'adb' command-line tool isn't in your $PATH, set adb location to constructor shown as below
-# adb = AdbSdkLib::Adb.new(<adb location>)
+# adb = AdbSdkLib::Adb.new('/path/to/adb')
 
 # Get device objects
 devices = adb.devices
 ```
 
-**Adb** object is wrapper of *com.android.ddmlib.AndroidDebugBridge*.  
+*Adb* object is wrapper of *com.android.ddmlib.AndroidDebugBridge*.  
 Source code of *com.android.ddmlib.AndroidDebugBridge*:
 <https://android.googlesource.com/platform/tools/base/+/master/ddmlib/src/main/java/com/android/ddmlib/AndroidDebugBridge.java>
 
@@ -34,12 +34,14 @@ Some methods of *AndroidDebugBridge* are wrapped for Ruby.
 For remaining methods, *Adb#method_missing* is defined to call
 wrapping java object's same name method using specified parameters.
 
-### Device Object
+### *Device* object
 
 ```ruby
 adb = AdbSdkLib::Adb.new
 device = adb.devices.first
-# device = adb.devices['xxxxxx'] # get by serial number of the device.
+# device = adb.devices['xxxxxx'] # get by the device's serial number.
+
+# Display attributes
 puts <<"EOS"
 serial    : #{device.serial}
 state     : #{device.state}
@@ -48,16 +50,28 @@ build ver : #{device.build_version}
 api level : #{device.api_level}
 device model  : #{device.device_model}
 manufacturer  : #{device.manufacturer}
-build desc    : #{device.property('ro.build.description')}
-battery level : #{device.battery_level}
 EOS
+
+# Push a file to the device
+device.push('local.txt', '/data/local/tmp/')
+
+# Pull a file from the device
+device.pull('/system/build.prop', '/path/to/dir/')
+
+# Execute shell
+puts device.shell('ps')  # display results
+
+device.shell('ls /data/local/tmp/') { |line|  # each line
+  puts line
+}
+
 ```
 
-**Device** object is wrapper of *com.android.ddmlib.Device*.  
+*Device* object is wrapper of *com.android.ddmlib.Device*.  
 Source code of *com.android.ddmlib.Device*:
 <https://android.googlesource.com/platform/tools/base/+/master/ddmlib/src/main/java/com/android/ddmlib/Device.java>
 
-Some methods of *ddmlib.Device* are wrapped for Ruby.
+Some methods of *ddmlib.Device* are wrapped for Ruby.  
 For remaining methods, *Device#method_missing* is defined to call
 wrapping java object's same name method using specified parameters.
 

data/adb-sdklib.gemspec

@@ -6,7 +6,7 @@ require 'adb_sdklib/version'
 Gem::Specification.new do |spec|
   spec.name          = "adb-sdklib"
   spec.version       = AdbSdkLib::VERSION
-  spec.authors       = ["yoyo"]
+  spec.authors       = ["yoyo0906"]
   spec.email         = ["yoyo0906@gmail.com"]
   spec.summary       = "Android Debug Bridge (ADB) wrapper" +
                        " using Android SDK Tools Library with Rjb."

data/lib/adb-sdklib.rb

@@ -4,50 +4,107 @@ require 'adb_sdklib/common'
 require 'adb_sdklib/device'
 
 module AdbSdkLib
+  # List of devices.
+  # It can be used as Enumerable like Set, and as Hash which key
+  #   is the serial number of the device.
+  class DeviceList < Hash
+    # @param [Enumerable] devices Device object of Java
+    def initialize(devices = [])
+      devices.each { |d| self[d.serial_number] = d }
+    end
+    # Calls block once for each device in self, passing that device as a parameter.
+    # If no block is given, an enumerator is returned instead.
+    # @return [Enumerator] if not block given
+    # @return [self] if block given
+    # @yield [device] called with each device
+    # @yieldparam [Device] device a device instance
+    def each
+      return self.values.each unless block_given?
+      self.values.each {|device| yield device }
+      return self
+    end
+  end
+  
   class Adb
     include Common
 
-    @@AndroidDebugBridge = nil
+    # @private
+    @@java_initialized = false
 
+    # @private
+    # AndroidDebugBridge class object
+    @@adb = nil
+
+    # Initialize Rjb and connect to ADB.
+    # @param [String] adb_location Location of ADB command line tool
+    # @param [Boolean] force_new_bridge if set true, start force new ADB server
+    # @raise [AdbError] If could not found ADB command line tool
     def initialize(adb_location = nil, force_new_bridge = false)
       if adb_location.nil?
         @adbpath = `which adb`.chomp!
+        raise AdbError, "Not found 'adb' command in $PATH" unless @adbpath
       else
         @adbpath = adb_location
+        raise AdbError, "Not found 'adb' command" unless @adbpath
       end
-      raise AdbError, "Not found 'adb' command in $PATH" unless @adbpath
-
-      # load AndroidDebugBridge
-      libpath = File.expand_path('../tools/lib/', File.dirname(@adbpath))
 
-      if @@AndroidDebugBridge.nil?
-        load_jar("#{libpath}/ddmlib.jar")
-        @@AndroidDebugBridge = Rjb::import('com.android.ddmlib.AndroidDebugBridge')
-        @@AndroidDebugBridge.initIfNeeded(false)
+      # load jar files
+      unless @@java_initialized
+        load_sdk_tools_jar(['ddmlib.jar'])
+        # Hide logs to be output to the console.
+        ddm = Rjb::import('com.android.ddmlib.DdmPreferences')
+        ddm.setLogLevel('assert')
+        @@java_initialized = true
         at_exit { Adb.terminate }
       end
+      if @@adb.nil?
+        @@adb = Rjb::import('com.android.ddmlib.AndroidDebugBridge')
+        @@adb.initIfNeeded(false)
+      end
 
-      @adb = @@AndroidDebugBridge.createBridge(@adbpath, force_new_bridge)
+      @adb = @@adb.createBridge(@adbpath, force_new_bridge)
       10.times { |i|
         break if @adb.connected?
         sleep(0.25)
       }
       raise AdbError, 'Connect adb error (timeout)' unless @adb.connected?
+      
+      @devices = DeviceList.new
     end
 
+    # Terminate ADB connection.
+    # This method will be called automatically when exiting ruby.
+    # @return [self] self
     def self.terminate
-      unless @@AndroidDebugBridge.nil?
-        @@AndroidDebugBridge.terminate
-        @@AndroidDebugBridge = nil
+      unless @@adb.nil?
+        @@adb.terminate
+        @@adb = nil
       end
+      self
     end
 
+    # Get devices attached with ADB.
+    # @return [DeviceList] List of devices
     def devices
-      devices = @adb.devices.map { |d| Device.new(d) }
-      class << devices
-        def [](serial); self.find { |d| d.serial_number == serial  } end
+      devices = @adb.devices.map { |d|
+        serial = d.serial_number
+        (@devices.has_key?(serial) && same_jobject?(@devices[serial].jobject, d)) \
+          ? @devices[serial] : Device.new(d)
+      }
+      @devices = DeviceList.new(devices)
+      return @devices
+    end
+
+    private
+    
+    # @private
+    def load_sdk_tools_jar(libs)
+      libpath = File.expand_path('../tools/lib/', File.dirname(@adbpath))
+      libs.each do |lib|
+        lib = "#{libpath}/#{lib}"
+        raise AdbError, "Not found #{lib}" unless File.exist?(lib)
+        Rjb::add_jar(lib)
       end
-      return devices
     end
   end
 end

data/lib/adb_sdklib/common.rb

@@ -2,14 +2,79 @@
 require 'rjb'
 
 module AdbSdkLib
+  # ADB error
   class AdbError < StandardError; end
+  
+  # Error on java
+  class SdkLibError < StandardError
+    # @return [String] error message
+    attr_reader :error_message
+    # @return [String] exception class name on Java
+    attr_reader :exception_name
+    # @return [String] class name
+    attr_reader :class_name
+    # @return [String] method name
+    attr_reader :method_name
+    
+    # @param [String] message error message
+    # @param [String] exception_name exception class name on Java
+    # @param [String] class_name class name
+    # @param [String] method_name method name
+    def initialize(message, exception_name, class_name, method_name)
+      super("#{message} (#{exception_name}) - [#{class_name}##{method_name}()]")
+      @error_message = message
+      @exception_name = exception_name
+      @class_name = class_name
+      @method_name = method_name
+    end
+  end
 
-  module Common
-    def load_jar(lib)
-      raise AdbError, "Not found #{lib}" unless File.exist?(lib)
-      Rjb::load(lib)
+  # @private
+  class CommandCapture
+    def initialize(line_receiver = nil)
+      @output = ''
+      @line_receiver = line_receiver
+    end
+    
+    # Override
+    def addOutput(data, offset, length)
+      out = data[offset..(offset + length - 1)] # -1 for ¥x00
+      @output << out.force_encoding('UTF-8')
+      unless @line_receiver.nil?
+        lines = @output.split("\n")
+        @output = (@output[-1] != "\n") ? lines.pop : ''
+        lines.each { |line|
+          @line_receiver.call(line.chomp)
+        }
+      end
+    end
+
+    # Override
+    def flush
+      if !@line_receiver.nil? && !@output.empty?
+        @line_receiver.call(@output)
+        @output = ''
+      end
     end
 
+    # Override
+    def isCancelled; false end
+    
+    def to_s; @output end
+  end
+  
+  # @private
+  module Common
+    # @private
+    System = Rjb::import('java.lang.System')
+
+    # Inspects whether two objects are the same of Java instance.
+    def same_jobject?(obj1, obj2)
+      System.identityHashCode(obj1) \
+        == System.identityHashCode(obj2)
+    end
+    
+    # Converts Java Map object to Ruby Hash object.
     def convert_map_to_hash(object, &block)
       hash = Hash.new
       i = object.entrySet.iterator
@@ -27,7 +92,7 @@ module AdbSdkLib
       hash
     end
 
-    module_function(:load_jar, :convert_map_to_hash)
+    module_function(:same_jobject?, :convert_map_to_hash)
   end
 end
 

data/lib/adb_sdklib/device.rb

@@ -1,61 +1,218 @@
 # coding: utf-8
 require 'adb_sdklib/common'
+require 'fileutils'
 
 module AdbSdkLib
+
+  # One of android device attached to host through ADB.
+  # 
+  # This is a wrapper of com.android.ddmlib.Device object in Java.
   class Device
     include Common
 
+    # @param [Rjb::Rjb_JavaProxy] device Rjb proxy object of com.android.ddmlib.Device
     def initialize(device)
       unless device.instance_of?(Rjb::Rjb_JavaProxy) &&
-          device.getClass.getCanonicalName == 'com.android.ddmlib.Device'
+          device._classname == 'com.android.ddmlib.Device'
         raise TypeError, "Parameter is not com.android.ddmlib.Device class"
       end
+      class << device
+        def call_java_method(method_name, *args)
+          rjb_method_missing(method_name, *args)
+        rescue => e
+          raise SdkLibError.new(e.message, e.class.to_s, self._classname, method_name)
+        end
+        alias_method :rjb_method_missing, :method_missing
+        alias_method :method_missing, :call_java_method
+      end
       @device = device
     end
 
-    def serial;          @device.serial_number end
-    def state;           @device.state.toString.to_sym end
-    def online?;         @device.online?     end
-    def emulator?;       @device.emulator?   end
-    def offline?;        @device.offline?    end
-    def bootloader?;     @device.bootloader? end
-    def reboot(into=nil) @device.reboot(into) end
-    def property_count;  @device.property_count end
-    def property(prop);  @device.property(prop) end
+    # @!attribute [r] jobject
+    # @return [Rjb::Rjb_JavaProxy] Wrapper of com.android.ddmlib.Device object.
+    def jobject;         @device end
+    
+    # @!attribute [r] serial
+    # @return [String] the serial number of the device.
+    def serial;          @device.getSerialNumber end
+    
+    # @!attribute [r] state
+    # @return [Symbol] the state of the device.
+    #   (:BOOTLOADER, :OFFLINE, :ONLINE, :RECOVERY)
+    def state;           @device.getState.toString.to_sym end
+    
+    # @!attribute [r] online?
+    # @return [Boolean] true if the device is ready.
+    def online?;         @device.isOnline end
+    
+    # @!attribute [r] emulator?
+    # @return [Boolean] true if the device is an emulator.
+    def emulator?;       @device.isEmulator end
+    
+    # @!attribute [r] offline?
+    # @return [Boolean] true if the device is offline.
+    def offline?;        @device.isOffline end
+    
+    # @!attribute [r] bootloader?
+    # @return [Boolean] true if the device is in bootloader mode.
+    def bootloader?;     @device.isBootloader end
+    
+    # Reboot the device
+    # @param [String, nil] into the bootloader name to reboot into,
+    #   or nil to just reboot the device
+    # @return [self]
+    def reboot(into=nil) @device.reboot(into); self end
+    
+    # Returns the property count.
+    # @return [Integer] the number of property for this device.
+    def property_count;  @device.getPropertyCount end
+    
+    # Returns a property value.
+    # @param [String] name the name of the value to return.
+    # @return [String, nil] the value or nil if the property does not exist.
+    def property(name);  @device.getProperty(name) end
+    
+    # Returns the device properties. It contains the whole output of 'getprop'
+    # @return [Hash<String, String>] the device properties
     def properties
-      convert_map_to_hash(@device.properties) { |hash, key, value|
+      convert_map_to_hash(@device.getProperties) do |hash, key, value|
         hash[key.toString] = value.toString
-      }
+      end
     end
-    def build_version;   @device.property(@device.PROP_BUILD_VERSION) end
-    def api_level;       @device.property(@device.PROP_BUILD_API_LEVEL) end
-    def build_codename;  @device.property(@device.PROP_BUILD_CODENAME) end
-    def device_model;    @device.property(@device.PROP_DEVICE_MODEL) end
-    def device_manufacturer; @device.property(@device.PROP_DEVICE_MANUFACTURER) end
-    def debuggable;      @device.property(@device.PROP_DEBUGGABLE) end
-
-    def battery_level(freshness_ms=nil)
+
+    # the build version of the android on the device.
+    # (same as output of 'getprop ro.build.version.release')
+    # @!attribute [r] build_version 
+    # @return [String] the build version of the android.
+    def build_version;   property(@device.PROP_BUILD_VERSION) end
+
+    # the API level of the android on the device.
+    # (same as output of 'getprop ro.build.version.sdk')
+    # @!attribute [r] api_level
+    # @return [String] the API level.
+    def api_level;       property(@device.PROP_BUILD_API_LEVEL) end
+
+    # the build code name of the android on the device.
+    # @!attribute [r] build_codename
+    # (same as output of 'getprop ro.build.version.codename')
+    # @return [String] the build code name.
+    def build_codename;  property(@device.PROP_BUILD_CODENAME) end
+
+    # the product model of the device.
+    # (same as output of 'getprop ro.product.model')
+    # @!attribute [r] device_model
+    # @return [String] the device model.
+    def device_model;    property(@device.PROP_DEVICE_MODEL) end
+
+    # the product manufacturer of the device.
+    # (same as output of 'getprop ro.product.manufacturer')
+    # @!attribute [r] device_manufacturer
+    # @return [String] the product manufacturer.
+    def device_manufacturer; property(@device.PROP_DEVICE_MANUFACTURER) end
+
+    # the device debuggable.
+    # (same as output of 'getprop ro.debuggable')
+    # @!attribute [r] debuggable
+    # @return [String] the device debuggable.
+    def debuggable;      property(@device.PROP_DEBUGGABLE) end
+
+    # Returns the battery level.
+    # @param [Integer] freshness_ms freshness time (milliseconds).
+    # @return [Integer] the battery level.
+    def battery_level(freshness_ms = nil)
       if freshness_ms.nil?
-        @device.battery_level.int_value
+        @device.getBatteryLevel.intValue
       else
-        @device.battery_level(freshness_ms).int_value
+        @device.getBatteryLevel(freshness_ms).intValue
       end
     end
     
-    def method_missing(action, *args)
-      return @device.__send__(action, *args)
+    # Executes a shell command on the device, and receives the result.
+    # @!method shell(command)
+    # @return [String, self]
+    # @overload shell(command)
+    #   @param [String] command the command to execute
+    #   @return [String] all results of the command.
+    # @overload shell(command)
+    #   @param [String] command the command to execute
+    #   @return [self] self
+    #   @yield [line]
+    #   @yieldparam [String] line each line of results of the command.
+    def shell(command, &block)
+      capture = CommandCapture.new(block_given? ? block : nil)
+      receiver = Rjb::bind(capture, 'com.android.ddmlib.IShellOutputReceiver')
+      @device.executeShellCommand(command.to_s, receiver)
+      block_given? ? self : capture.to_s
+    end
+
+    # Pushes a file to the device.
+    # 
+    # If *remotefile* path ends with '/', complements by the basename of
+    # *localfile*.
+    # @example
+    #   device = AdbSdkLib::Adb.new.devices.first
+    #   device.push('path/to/local.txt', '/data/local/tmp/remote.txt')
+    #   device.push('path/to/file.txt', '/data/local/tmp/') # uses file.txt
+    # @param [String] localfile the name of the local file to send
+    # @param [String] remotefile the name of the remote file or directory
+    #   on the device
+    # @return [self] self
+    # @raise [ArgumentError] If *localfile* is not found
+    def push(localfile, remotefile)
+      raise ArgumentError, "Not found #{localfile}" unless File.exist?(localfile)
+      if remotefile.end_with?('/')
+        remotefile = "#{remotefile}#{File.basename(localfile)}"
+      end
+      @device.pushFile(localfile, remotefile)
+      self
     end
 
-    def to_s
-      "Android: ID:#{self.serial}"
+    # Pulls a file from the device.
+    # 
+    # If *localfile* path ends with '/', complements by the basename of
+    # *remotefile*.
+    # @example
+    #   device = AdbSdkLib::Adb.new.devices.first
+    #   device.pull('/data/local/tmp/remote.txt', 'path/to/local.txt')
+    #   device.pull('/data/local/tmp/file.txt', 'path/to/dir/') # uses file.txt
+    # @param [String] remotefile the name of the remote file on the device to get
+    # @param [String] localfile the name of the local file or directory
+    # @return [self] self
+    def pull(remotefile, localfile)
+      if localfile.end_with?('/') || File.directory?(localfile)
+        localdir = localfile.chomp('/')
+        localfilename = nil
+      else
+        localdir = File.dirname(localfile)
+        localfilename = File.basename(localfile)
+      end
+      unless File.exist?(localdir)
+        FileUtils.mkdir_p(localdir)
+      end
+      
+      localfilename = File.basename(remotefile) if localfilename.nil?
+      @device.pullFile(remotefile, "#{localdir}/#{localfilename}")
+      self
     end
 
-    def inspect
-      "#<AdbSdkLib::Device:#{self.serial}>"
+    # Calls wrapping java object's same name method with arguments.
+    # @param [String] method_name method name to call
+    # @param [Array] args arguments
+    # @return [Object] result of the method call
+    def method_missing(method_name, *args)
+      return @device.__send__(method_name, *args)
     end
 
+    # Converts self to string.
+    # @return [String] convert to string
+    def to_s; "Android:#{self.serial}" end
+
+    # Returns the human-readable formatted information.
+    # @return [String] the human-readable formatted information
+    def inspect; "#<AdbSdkLib::Device:#{self.serial}>" end
+
     private
+    # @private
     def to_ary; nil end
   end
 end
-

data/lib/adb_sdklib/version.rb

@@ -1,3 +1,3 @@
 module AdbSdkLib
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: adb-sdklib
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
-- yoyo
+- yoyo0906
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-17 00:00:00.000000000 Z
+date: 2014-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rjb
@@ -61,6 +61,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .yardopts
 - Gemfile
 - LICENSE.txt
 - README.md