robust_excel_ole 1.10 → 1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9645dff34f91fdb38da9b5a8375e17170bace4159355b126b142cb4ab6689bf
-  data.tar.gz: d0ca3dbd87bca685ecb98ba1ac747b427c430e52bfe3de5b14beccfefd30d94c
+  metadata.gz: 344c336ba61c5f1b98839047f69cbbac1ddef451291fa32260c47218421d78cc
+  data.tar.gz: 169a63ca7cb3d582443aa046228797cc946e9f47f45e97019b21504f8a897384
 SHA512:
-  metadata.gz: ae0be8a8538c3dd3c27a44c3d11d781be260cb2898e1cf221925d0902160ef4104b9142fd99c106ee5f210aa83688fa062d4ee1a13c8ae49dcb96b150b3baaeb
-  data.tar.gz: c21be14de79476461692a475685e518f478947051ac9cc8d417952646690b642e8dc2e52999a16b56c2cb8e337ac58b21ae2a28dfffbd8f89260aeced27d216b
+  metadata.gz: dc9e189d01012805dd02d668c833e96b9597997b518a2b9ce6beb671969e007d8cae5d362a045fbd439a4368cf7ddfdfee66b535d60e9b4e9c68db7a99023989
+  data.tar.gz: 1e04fa12bc2e5956fb0efa68a92b185557b8180909da820517ab55affd3bf8154d297aa9a2b0eaa8e8a161fc31972560ea74f5beefa2fc51225f45b392c122fc

data/Changelog

@@ -1,6 +1,14 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+
+## [1.11]
+
+### Added
+  - Range#==, Worksheet#== 
+  - Workbook#open: options :if_blocked is synonym to :if_obstructed
+  - Simplified Code
+
 ## [1.10]
 
 ### Added

data/README.rdoc

@@ -9,7 +9,7 @@ RobustExcelOle works by sending VBA methods via Win32OLE. It keeps track of Exce
 
 == Requirements
 
-* Ruby 1.8.6 or higher
+  Ruby 2.1 or higher. Most functions run on Ruby 1.8.6, too.
 
 == Installation
 
@@ -134,6 +134,8 @@ or, using abbreviations,
 
   workbook = Workbook.open('spec/data/workbook.xls', :v => true)
 
+Note that Workbook.open can also connect to workbooks which were not opened via RobustExcelOle (but had been opened before by some user).
+
 For more details about opening workbooks see {README_open}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_open.rdoc]
  
 We can do a simple save
@@ -234,7 +236,7 @@ Similarly, if the user has opened a workbook that has the same name but a differ
 
   workbook1 = Workbook.open('spec/data/workbook.xls')
   # do something
-  workbook2 = Workbook.open('spec/data/more/workbook.xls', :if_obstructed => :forget)
+  workbook2 = Workbook.open('spec/data/more/workbook.xls', :if_blocked => :forget)
 
 For more details about opening and closing workbooks in Excel instances see {README_open}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_open.rdoc]
 
@@ -309,7 +311,7 @@ For more details about reading and writing contents of cells and ranges see {REA
 
 RobustExcelOle runs in jruby as well. You can call the console via the command +jreo+. However, note that, due to some restrictions of the library jruby-win32ole, there are some restrictions. So we had implemented some adaptions and workarounds. Some issues still remain when running under jruby:
 
-1. Excel.current or Excel.new(:reuse => true) does not connect to an already running Excel instance, unless some workbook has been opened via RobustExcelOle. 2. Excel.kill_all does work, Excel.close_all does not work. 3. When providing an absolute path, you have to state the "/" ("C:/abc.xls" works, "C:abc" does not work)
+1. Excel.current or Excel.new(:reuse => true) does not connect to an already running Excel instance, unless some workbook has been opened via RobustExcelOle. 2. Excel.kill_all does work, Excel.close_all does not work. 3. When providing an absolute path, you have to state the "/" ("C:/abc.xls" works, "C:abc" does not work).
 
 
 
@@ -329,7 +331,7 @@ You can run the examples included in the directory +examples+, e.g.
 
 This project RobustExcelOle is work in progress. We are happy to implement further features. So we invite you to send your pull requests. We then strive to realize them as soon as possible. If you have any feedback, or you find use cases that RobustExcelOle does not satisfy, please let us know.
 
-RobustExcelOle is being tested for Excel 2010. It can be used for any recent Excel Office version.
+RobustExcelOle is being tested for Excel 2010 and Excel 2013. It can be used for any recent Excel Office version. Most functions should run on Excel 2007 as well.
 
 RobustExcelOle has been optimised with help of the rubocop and the rcov tool. 
 

data/docs/README_open.rdoc

@@ -25,23 +25,24 @@ The options are the following:
 
 +:excel+ and +:visible+ are options stated in +:default+ or +:force+
 
-+:excel+::          specifies the Excel instance. 
++:excel+::             specifies the Excel instance. 
 
-+:visible+::        makes the workbook visible or invisible
++:visible+::           makes the workbook visible or invisible
 
-+:if_unsaved+::      specify behaviour if the workbook was unsaved (default: +:raise+)
++:if_unsaved+::        specifies behaviour if the workbook was unsaved (default: +:raise+)
 
-+:if_obstructed+::   specify behaviour if the workbook is blocked by another book (default: +:raise+)
++:if_blocked::         specifies behaviour if the workbook is blocked by another book (default: +:raise+)
 
-+:read_only+::       open in read-only mode (default: +false+)
 
-+:check_compatibility:: check compatibility when saving
++:read_only+::          opens in read-only mode (default: +false+)
 
-+:calculation+::     forces the calculation mode to be manual (:manual) or automatic (:automatic)
++:check_compatibility:: checks compatibility when saving
 
-+:if_absent+::       specify behaviour if the workbook with the given file name does not exist if the workbook does not exist (default: +create+)
++:calculation+::        forces the calculation mode to be manual (:manual) or automatic (:automatic)
 
-You can use the following abbreviations: +:f+ for  +:force+, +:d+ for +:default+, +:e+ for +:excel+, and +:v+ for +:visible+. Finally you can leave out the option +:force+ or +:f+.
++:if_absent+::          specifies behaviour if the workbook with the given file name does not exist if the workbook does not exist (default: +create+)
+
+You can use the following abbreviations or synonyms: +:f+ for  +:force+, +:d+ for +:default+, +:e+ for +:excel+, and +:v+ for +:visible+, +:if_obstructed+ for +:if_blocked+. Finally you can leave out the option +:force+ or +:f+.
 
 The option +:excel+ :
 
@@ -57,7 +58,7 @@ If a workbook contains unsaved changes and a new workbook with the same file nam
 +:new_excel+:: Open the new workbook in a new Excel instance
 +:alert+::   Give control to Excel.
 
-The option +:if_obstructed+ :
+The option +:if_blocked+ : 
 
 If a workbook is open and a new workbook with same name and a different path is open, then
 
@@ -122,9 +123,9 @@ If a workbook contains unsaved changes and a workbook with the same filename sha
 
   book = Workbook.open('spec/data/workbook.xls', :if_unsaved => :accept)
 
-If a workbook is open and a workbook with the same name but in different path shall be opened, i.e. the first workbook blocks opening the other workbook, then the option +:if_obstructed+ handles this situation, e.g.
+If a workbook is open and a workbook with the same name but in different path shall be opened, i.e. the first workbook blocks opening the other workbook, then the option +:if_blocked+ handles this situation, e.g.
 
-  book = Workbook.open('path/workbook.xls', :if_obstructed => :forget)
+  book = Workbook.open('path/workbook.xls', :if_blocked => :forget)
 
 Remarks:
 
@@ -150,6 +151,10 @@ A Workbook object can be created when giving an Excel workbook.
 
    book = Workbook.new(win32ole_workbook)
 
+Note that only a restricted number of options can be considered, e.g. +:visible+
+
+   book = Workbook.new(win32ole_workbook, :visible => true)
+
 === Unobtrusively modifying a workbook
 
 The method +unobtrusively+ enables the user to read or modify a workbook, no matter if it is open in some Excel instance, if it is saved or unsaved, and if it is writable or not. When opening a workbook unobtrusively, its status remains unchanged. This status includes, whether the workbook is opened or closed, saved or unsaved, readonly or writable, visible or invisible, calculation mode is automatic or manual, and checking compatibility is turned on or off. 
@@ -182,7 +187,7 @@ The methods +for_reading+ and +for_modifying+ indicate unobtrusively reading or
     sheet[1,1] = "c" 
   end
 
-Remark: The methods +unobtrusively+, +for_reading+ and +for_modifying+ work only for workbooks opened via RobustExcelOle. They do not connect to workbooks opened outside RobustExcelOle.
+Note, that the methods +unobtrusively+, +for_reading+ and +for_modifying+ work not only for workbooks opened via RobustExcelOle, but do also connect to workbooks opened outside RobustExcelOle.
 
 === Retaining the saved-status
 

data/lib/robust_excel_ole/bookstore.rb

@@ -16,24 +16,25 @@ module RobustExcelOle
       book.excel
     end
 
-    # returns a book with the given filename, if it was open once
+    # returns a workbook with the given filename, if it was open once
     # @param [String] filename  the file name
     # @param [Hash]   options   the options
     # @option option [Boolean] :prefer_writable
     # @option option [Boolean] :prefer_excel
-    # prefers open books to closed books, and among them, prefers more recently opened books
+    # prefers open workbooks to closed workbooks, and among them, prefers more recently opened workbooks
     # excludes hidden Excel instance
-    # options: :prefer_writable   returns the writable book, if it is open (default: true)
-    #                             otherwise returns the book according to the preference order mentioned above
-    #          :prefer_excel      returns the book in the given Excel instance, if it exists,
+    # options: :prefer_writable   returns the writable workbook, if it is open (default: true)
+    #                             otherwise returns the workbook according to the preference order mentioned above
+    #          :prefer_excel      returns the workbook in the given Excel instance, if it exists,
     #                             otherwise proceeds according to prefer_writable
     def fetch(filename, options = { :prefer_writable => true })
       return nil unless filename
 
       filename = General.absolute_path(filename)
       filename_key = General.canonize(filename)
-      weakref_books = @filename2books[filename_key]
-      return nil unless weakref_books
+      weakref_books = @filename2books[filename_key]      
+      weakref_books = consider_networkpaths(filename_key) if weakref_books.empty? || weakref_books.nil?
+      return nil if weakref_books.nil? || weakref_books.empty?
 
       result = open_book = closed_book = nil
       weakref_books = weakref_books.map { |wr_book| wr_book if wr_book.weakref_alive? }.compact
@@ -44,8 +45,7 @@ module RobustExcelOle
           begin
             @filename2books[filename_key].delete(wr_book)
           rescue
-            # trace "#{$!.message}"
-            # trace "Warning: deleting dead reference failed: file: #{filename.inspect}"
+            trace "Warning: deleting dead reference failed: file: #{filename.inspect}"
           end
         else
           book = wr_book.__getobj__
@@ -67,6 +67,92 @@ module RobustExcelOle
       result
     end
 
+    def consider_networkpaths(filename)      
+      network = WIN32OLE.new('WScript.Network')
+      drives = network.enumnetworkdrives
+      drive_letter, filename_after_drive_letter = filename.split(':')   
+      # if filename starts with a drive letter not c and this drive exists,
+      # then if there is the corresponding host_share_path in the bookstore, 
+      # then take the corresponding workbooks
+      # otherwise (there is an usual file path) find in the bookstore the workbooks of which filenames 
+      # ends with the latter part of the given filename (after the drive letter)
+      if drive_letter != 'c' && drive_letter != filename    
+        for i in 0 .. drives.Count-1
+          next if i % 2 == 1
+          if drives.Item(i).gsub(':','').downcase == drive_letter
+            hostname_share = drives.Item(i+1).gsub('\\','/').gsub('//','').downcase
+            break
+          end
+        end
+        found_filename = nil
+        @filename2books.each do |stored_filename,_|
+          if hostname_share && stored_filename
+            if stored_filename[0] == '/'
+              index_hostname = stored_filename[1,stored_filename.length].index('/')+2
+              index_hostname_share = stored_filename[index_hostname,stored_filename.length].index('/')
+              hostname_share_in_stored_filename = stored_filename[1,index_hostname+index_hostname_share-1] 
+              if hostname_share_in_stored_filename == hostname_share
+                found_filename = stored_filename
+                break
+              end
+            elsif found_filename.nil? && stored_filename.end_with?(filename_after_drive_letter)
+              found_filename = stored_filename
+            end
+          end
+        end
+      elsif filename[0] == '/'
+        # if filename starts with a host name and share, and this is an existing host name share path,
+        # then if there are workbooks with the corresponding drive letter,
+        # then take these workbooks,
+        # otherwise (there is an usual file path) find in the bookstore the workbooks of which filenames
+        # ends with the latter part of the given filename (after the drive letter)
+        index_hostname = filename[1,filename.length].index('/')+2
+        index_hostname_share = filename[index_hostname,filename.length].index('/')
+        hostname_share_in_filename = filename[1,index_hostname+index_hostname_share-1] 
+        filename_after_hostname_share = filename[index_hostname+index_hostname_share+1, filename.length]
+        require 'socket'
+        hostname = Socket.gethostname
+        if hostname_share_in_filename[0,hostname_share_in_filename.index('/')] == hostname.downcase
+          for i in 0 .. drives.Count-1
+            next if i % 2 == 1
+            hostname_share = drives.Item(i+1).gsub('\\','/').gsub('//','').downcase
+            if hostname_share == hostname_share_in_filename
+              drive_letter = drives.Item(i).gsub(':','').downcase
+              break
+            end
+          end
+          @filename2books.each do |stored_filename,_|
+            if stored_filename
+              if drive_letter && stored_filename.start_with?(drive_letter.downcase) && stored_filename.end_with?(filename_after_hostname_share)
+                found_filename = stored_filename
+                break
+              elsif found_filename.nil? && stored_filename.end_with?(filename_after_hostname_share)
+                found_filename = stored_filename
+              end
+            end
+          end
+        end
+      else
+        # if filename is an usual file path,
+        # then find in the bookstore a workbook of which filename starts with
+        # a drive letter or a host name
+        @filename2books.each do |stored_filename,_|
+          drive_letter, _ = stored_filename.split(':')   
+          stored_filename_end = if drive_letter != stored_filename && drive_letter != 'c'
+            stored_filename[stored_filename.index(':')+1,stored_filename.length]
+          elsif stored_filename[0] == '/'
+            index_after_hostname = stored_filename[1,stored_filename.length].index('/')
+            stored_filename[index_after_hostname+1, stored_filename.length]
+          end
+          if stored_filename_end && filename.end_with?(stored_filename_end)
+            found_filename = stored_filename
+            break
+          end
+        end
+      end
+      @filename2books[found_filename]
+    end
+
     # stores a workbook
     # @param [Workbook] book a given book
     def store(book)

data/lib/robust_excel_ole/excel.rb

@@ -76,14 +76,15 @@ module RobustExcelOle
       ole_xl = win32ole_excel unless win32ole_excel.nil?
       options = { :reuse => true }.merge(options)
       #ole_xl = current_excel if options[:reuse] == true
-      if options[:reuse] == true
-        ole_xl = if RUBY_PLATFORM =~ /java/
-          excel_instance = known_excel_instance
-          ole_xl = excel_instance.ole_excel unless excel_instance.nil?
+      if options[:reuse] == true && ole_xl.nil?
+        ole_xl = if RUBY_PLATFORM =~ /java/         
+          excel_instance = known_excel_instance if excel_instance.nil?
+          excel_instance.ole_excel unless excel_instance.nil?
         else
           current_excel
         end
       end
+      connected = (not ole_xl.nil?)
       ole_xl ||= WIN32OLE.new('Excel.Application')
       hwnd = ole_xl.HWnd
       stored = hwnd2excel(hwnd)
@@ -98,11 +99,11 @@ module RobustExcelOle
 
       unless options.is_a? WIN32OLE
         begin
-          reused = options[:reuse] && stored && stored.alive?
-          unless reused
+          reused = options[:reuse] && stored && stored.alive? 
+          if (not reused) && (not connected)
             options = { :displayalerts => :if_visible, :visible => false, :screenupdating => true }.merge(options)
           end
-          result.visible = options[:visible] unless options[:visible].nil?
+          result.visible = options[:visible] unless options[:visible].nil? 
           result.displayalerts = options[:displayalerts] unless options[:displayalerts].nil?
           result.calculation = options[:calculation] unless options[:calculation].nil?
           result.screenupdating = options[:screenupdating] unless options[:screenupdating].nil?
@@ -423,6 +424,10 @@ module RobustExcelOle
       processes.select { |p| p.name == 'EXCEL.EXE' }.size
     end
 
+    def self.known_excels_number
+      @@hwnd2excel.size
+    end
+
     # returns an Excel instance
     def self.known_excel_instance
       @@hwnd2excel.each do |hwnd, wr_excel|

data/lib/robust_excel_ole/general.rb

@@ -67,13 +67,26 @@ class WIN32OLE
   
   # promoting WIN32OLE objects to RobustExcelOle objects
   def to_reo
-    case ole_type.name
-    when 'Range' then RobustExcelOle::Range.new(self)
-    when '_Worksheet' then RobustExcelOle::Worksheet.new(self)
-    when '_Workbook' then RobustExcelOle::Workbook.new(self)
-    when '_Application' then RobustExcelOle::Excel.new(self)
-    else
-      self
+    begin
+      self.Hwnd
+      RobustExcelOle::Excel.new(self)
+    rescue
+      begin
+        self.FullName
+        RobustExcelOle::Workbook.new(self)
+      rescue
+        begin
+          self.Copy
+          RobustExcelOle::Worksheet.new(self)
+        rescue          
+          begin
+            self.Address
+            RobustExcelOle::Range.new(self)        
+          rescue
+            self
+          end
+        end
+      end
     end
   end
 end

data/lib/robust_excel_ole/range.rb

@@ -213,6 +213,12 @@ module RobustExcelOle
       end
     end
 
+    def == other_range
+      other_range.is_a?(Range) &&
+        self.worksheet == other_range.worksheet
+        self.Address == other_range.Address 
+    end
+
     # @private
     def self.worksheet_class   
       @worksheet_class ||= begin

data/lib/robust_excel_ole/reo_common.rb

@@ -74,6 +74,14 @@ module RobustExcelOle
   class WorkbookBeingUsed < WorkbookREOError       
   end
 
+  # @private
+  class WorkbookConnectingNotAliveError < WorkbookREOError        
+  end
+
+  # @private
+  class WorkbookConnectingBlockingError < WorkbookREOError       
+  end
+
   # @private
   class FileNotFound < FileREOError                
   end

data/lib/robust_excel_ole/version.rb

@@ -1,3 +1,3 @@
 module RobustExcelOle
-  VERSION = "1.10"
+  VERSION = "1.11"
 end

data/lib/robust_excel_ole/workbook.rb

@@ -14,7 +14,6 @@ module RobustExcelOle
     attr_accessor :excel
     attr_accessor :ole_workbook
     attr_accessor :stored_filename
-    attr_accessor :options
     attr_accessor :modified_cells
     attr_reader :workbook
 
@@ -31,137 +30,116 @@ module RobustExcelOle
       :update_links => :never
     }.freeze
 
-    ABBREVIATIONS = [[:default,:d], [:force, :f], [:excel, :e], [:visible, :v]].freeze
-
-    class << self
-
-      # opens a workbook.
-      # @param [String] file the file name
-      # @param [Hash] opts the options
-      # @option opts [Hash] :default or :d
-      # @option opts [Hash] :force or :f
-      # @option opts [Symbol]  :if_unsaved     :raise (default), :forget, :accept, :alert, :excel, or :new_excel
-      # @option opts [Symbol]  :if_obstructed  :raise (default), :forget, :save, :close_if_saved, or _new_excel
-      # @option opts [Symbol]  :if_absent      :raise (default) or :create
-      # @option opts [Boolean] :read_only      true (default) or false
-      # @option opts [Boolean] :update_links   :never (default), :always, :alert
-      # @option opts [Boolean] :calculation    :manual, :automatic, or nil (default)
-      # options:
-      # :default : if the workbook was already open before, then use (unchange) its properties,
-      #            otherwise, i.e. if the workbook cannot be reopened, use the properties stated in :default
-      # :force   : no matter whether the workbook was already open before, use the properties stated in :force
-      # :default and :force contain: :excel, :visible
-      #  :excel   :current (or :active or :reuse)
-      #                    -> connects to a running (the first opened) Excel instance,
-      #                       excluding the hidden Excel instance, if it exists,
-      #                       otherwise opens in a new Excel instance.
-      #           :new     -> opens in a new Excel instance
-      #           <excel-instance> -> opens in the given Excel instance
-      #  :visible true, false, or nil (default)
-      #  alternatives: :default_excel, :force_excel, :visible, :d, :f, :e, :v
-      # :if_unsaved     if an unsaved workbook with the same name is open, then
-      #                  :raise               -> raises an exception
-      #                  :forget              -> close the unsaved workbook, open the new workbook
-      #                  :accept              -> lets the unsaved workbook open
-      #                  :alert or :excel     -> gives control to Excel
-      #                  :new_excel           -> opens the new workbook in a new Excel instance
-      # :if_obstructed  if a workbook with the same name in a different path is open, then
-      #                  :raise               -> raises an exception
-      #                  :forget              -> closes the old workbook, open the new workbook
-      #                  :save                -> saves the old workbook, close it, open the new workbook
-      #                  :close_if_saved      -> closes the old workbook and open the new workbook, if the old workbook is saved,
-      #                                          otherwise raises an exception.
-      #                  :new_excel           -> opens the new workbook in a new Excel instance
-      # :if_absent       :raise               -> raises an exception     , if the file does not exists
-      #                  :create              -> creates a new Excel file, if it does not exists
-      # :read_only            true -> opens in read-only mode
-      # :visible              true -> makes the workbook visible
-      # :check_compatibility  true -> check compatibility when saving
-      # :update_links         true -> user is being asked how to update links, false -> links are never updated
-      # @return [Workbook] a representation of a workbook
-      def open(file, opts = { }, &block)
-        options = @options = process_options(opts)
-        book = nil
-        if (options[:force][:excel] != :new) && (options[:force][:excel] != :reserved_new)
-          # if readonly is true, then prefer a book that is given in force_excel if this option is set
-          forced_excel = if options[:force][:excel]
-            options[:force][:excel] == :current ? excel_class.new(:reuse => true) : excel_of(options[:force][:excel])
-          end
-          book = bookstore.fetch(file,
-                  :prefer_writable => !(options[:read_only]),
-                  :prefer_excel    => (options[:read_only] ? forced_excel : nil)) rescue nil
-          if book
-            if (!(options[:force][:excel]) || (forced_excel == book.excel)) &&
-               !(book.alive? && !book.saved && (options[:if_unsaved] != :accept))
-              book.options = options
-              book.ensure_excel(options) # unless book.excel.alive?
-              # if the ReadOnly status shall be changed, save, close and reopen it
-              if book.alive? && ((!book.writable && !(options[:read_only])) ||
-                 (book.writable && options[:read_only]))
-                book.save if book.writable && !book.saved
-                book.close(:if_unsaved => :forget)
-              end
-              # reopens the book if it was closed
-              book.ensure_workbook(file,options) unless book.alive?
-              book.visible = options[:force][:visible] unless options[:force][:visible].nil?
-              book.CheckCompatibility = options[:check_compatibility] unless options[:check_compatibility].nil?
-              book.excel.calculation = options[:calculation] unless options[:calculation].nil?
-              return book
-            end
+    ABBREVIATIONS = [[:default,:d], [:force, :f], [:excel, :e], [:visible, :v],
+                     [:if_obstructed, :if_blocked]].freeze
+
+
+    # opens a workbook.
+    # @param [String] file the file name
+    # @param [Hash] opts the options
+    # @option opts [Hash] :default or :d
+    # @option opts [Hash] :force or :f
+    # @option opts [Symbol]  :if_unsaved     :raise (default), :forget, :accept, :alert, :excel, or :new_excel
+    # @option opts [Symbol]  :if_obstructed  :raise (default), :forget, :save, :close_if_saved, or _new_excel
+    # @option opts [Symbol]  :if_absent      :raise (default) or :create
+    # @option opts [Boolean] :read_only      true (default) or false
+    # @option opts [Boolean] :update_links   :never (default), :always, :alert
+    # @option opts [Boolean] :calculation    :manual, :automatic, or nil (default)
+    # options:
+    # :default : if the workbook was already open before, then use (unchange) its properties,
+    #            otherwise, i.e. if the workbook cannot be reopened, use the properties stated in :default
+    # :force   : no matter whether the workbook was already open before, use the properties stated in :force
+    # :default and :force contain: :excel, :visible
+    #  :excel   :current (or :active or :reuse)
+    #                    -> connects to a running (the first opened) Excel instance,
+    #                       excluding the hidden Excel instance, if it exists,
+    #                       otherwise opens in a new Excel instance.
+    #           :new     -> opens in a new Excel instance
+    #           <excel-instance> -> opens in the given Excel instance
+    #  :visible true, false, or nil (default)
+    #  alternatives: :default_excel, :force_excel, :visible, :d, :f, :e, :v
+    # :if_unsaved     if an unsaved workbook with the same name is open, then
+    #                  :raise               -> raises an exception
+    #                  :forget              -> close the unsaved workbook, open the new workbook
+    #                  :accept              -> lets the unsaved workbook open
+    #                  :alert or :excel     -> gives control to Excel
+    #                  :new_excel           -> opens the new workbook in a new Excel instance
+    # :if_obstructed  if a workbook with the same name in a different path is open, then
+    # or               :raise               -> raises an exception
+    # :if_blocked      :forget              -> closes the old workbook, open the new workbook
+    #                  :save                -> saves the old workbook, close it, open the new workbook
+    #                  :close_if_saved      -> closes the old workbook and open the new workbook, if the old workbook is saved,
+    #                                          otherwise raises an exception.
+    #                  :new_excel           -> opens the new workbook in a new Excel instance
+    # :if_absent       :raise               -> raises an exception     , if the file does not exists
+    #                  :create              -> creates a new Excel file, if it does not exists
+    # :read_only            true -> opens in read-only mode
+    # :visible              true -> makes the workbook visible
+    # :check_compatibility  true -> check compatibility when saving
+    # :update_links         true -> user is being asked how to update links, false -> links are never updated
+    # @return [Workbook] a representation of a workbook
+    def self.open(file, opts = { }, &block)
+      raise(FileNameNotGiven, 'filename is nil') if file.nil?
+      raise(FileNotFound, "file #{General.absolute_path(file).inspect} is a directory") if File.directory?(file)
+      options = process_options(opts)
+      book = nil
+      if options[:force][:excel] != :new
+        # if readonly is true, then prefer a book that is given in force_excel if this option is set       
+        forced_excel = if RUBY_PLATFORM !~ /java/ 
+          (options[:force][:excel].nil? || options[:force][:excel] == :current) ? 
+            excel_class.new(:reuse => true) : excel_of(options[:force][:excel])
+        end
+        begin
+          book = if File.exists?(file)
+            bookstore.fetch(file, :prefer_writable => !(options[:read_only]),
+                                  :prefer_excel    => (options[:read_only] ? forced_excel : nil))
           end
+        rescue
+          trace "#{$!.message}"
         end
-        new(file, options, &block)
-      end
-    end
-
-    # creates a Workbook object by opening an Excel file given its filename
-    # or by promoting a Win32OLE object representing an Excel file
-    # @param [WIN32OLE] workbook a Win32Ole-workbook
-    # @param [Hash] opts the options as in Workbook::open
-    # @option opts [Symbol] see Workbook::open
-    # @return [Workbook] a workbook
-    def self.new(ole_workbook, opts = { }, &block)
-      opts = process_options(opts)
-      if ole_workbook && (ole_workbook.is_a? WIN32OLE)
-        filename = ole_workbook.Fullname.tr('\\','/') rescue nil
-        if filename
-          book = bookstore.fetch(filename)
-          if book && book.alive?
-            open(filename, opts)
-            #book.visible = opts[:force][:visible] unless opts[:force].nil? || opts[:force][:visible].nil?
-            #book.excel.calculation = opts[:calculation] unless opts[:calculation].nil?
-            #book.excel.displayalerts = opts[:calculation] unless opts[:calculation].nil?
+        if book          
+          if (!(options[:force][:excel]) || (forced_excel == book.excel)) &&
+             !(book.alive? && !book.saved && (options[:if_unsaved] != :accept))
+            book.ensure_excel(options) # unless book.excel.alive?
+            # if the ReadOnly status shall be changed, save, close and reopen it
+            # removed the feature for the next time
+            if book.alive? && ((!book.writable && !(options[:read_only])) ||
+               (book.writable && options[:read_only]))
+              book.save if book.writable && !book.saved
+              book.close(:if_unsaved => :forget)
+            end
+            # reopens the book if it was closed
+            book.ensure_workbook(file,options) unless book.alive?
+            book.visible = options[:force][:visible] unless options[:force][:visible].nil?
+            book.CheckCompatibility = options[:check_compatibility] unless options[:check_compatibility].nil?
+            book.excel.calculation = options[:calculation] unless options[:calculation].nil?
             return book
-          else
-            super(filename,opts)
           end
         end
-      else
-        super
       end
+      new(file, options, &block)
     end
-
+    
     # creates a new Workbook object, if a file name is given
     # Promotes the win32ole workbook to a Workbook object, if a win32ole-workbook is given
     # @param [Variant] file_or_workbook  file name or workbook
-    # @param [Hash]    opts              the options as in Workbook::open
+    # @param [Hash]    opts             
     # @option opts [Symbol] see above
     # @return [Workbook] a workbook
     def initialize(file_or_workbook, options = { }, &block)
-      # options = @options = self.class.process_options(options) if options.empty?
-      if file_or_workbook.is_a? WIN32OLE
+      options = self.class.process_options(options)
+      if file_or_workbook.is_a? WIN32OLE        
         workbook = file_or_workbook
         @ole_workbook = workbook
         # use the Excel instance where the workbook is opened
-        win32ole_excel = WIN32OLE.connect(workbook.Fullname).Application rescue nil
-        @excel = excel_class.new(win32ole_excel)
-        @excel.visible = options[force][:visible] unless options[:force][:visible].nil?
+        ole_excel = WIN32OLE.connect(workbook.Fullname).Application rescue nil
+        @excel = excel_class.new(ole_excel)
+        @excel.visible = options[:force][:visible] unless options[:force][:visible].nil?
         @excel.calculation = options[:calculation] unless options[:calculation].nil?
-        ensure_excel(options)
       else
-        file = file_or_workbook
+        filename = file_or_workbook        
         ensure_excel(options)
-        ensure_workbook(file, options)
+        ensure_workbook(filename, options)
       end
       bookstore.store(self)
       @modified_cells = []
@@ -177,7 +155,7 @@ module RobustExcelOle
       end
     end
 
-  private
+  private    
 
     # translates abbreviations and synonyms and merges with default options
     def self.process_options(options, proc_opts = {:use_defaults => true})
@@ -241,45 +219,81 @@ module RobustExcelOle
   public
 
     # @private
-    def ensure_excel(options)  
+    # ensures an excel but not for jruby if current Excel shall be used
+    def ensure_excel(options)
+      excel_option = options[:force][:excel].nil? ? options[:default][:excel] : options[:force][:excel]
+      @excel = if excel_option == :new
+        excel_class.new(:reuse => false) 
+      elsif excel_option.nil? || excel_option == :current
+        excel_class.new(:reuse => true) unless RUBY_PLATFORM =~ /java/
+      else  #elsif excel_options.is_a?(WIN32OLE) || excel_option.is_a?(Excel) #excel_option.respond_to?(:Hwnd)
+        self.class.excel_of(excel_option)
+      end
       if @excel && @excel.alive?
-        @excel.created = false
-        return
+        @excel.visible = options[:force][:visible] unless options[:force][:visible].nil?
+        @excel.calculation = options[:calculation] unless options[:calculation].nil?
       end
-      excel_option = options[:force].nil? || options[:force][:excel].nil? ? options[:default][:excel] : options[:force][:excel]
-      @excel = self.class.excel_of(excel_option) unless excel_option == :current || excel_option == :new || excel_option == :reserved_new
-      excel_class.new(:reuse => false) if (excel_option == :reserved_new) && Excel.known_excel_instances.empty?
-      @excel = excel_class.new(:reuse => (excel_option == :current)) unless @excel && @excel.alive?
-      @excel
     end
 
 
     # @private
+    # restriction for jruby: does not manage conflicts with blocking or unsaved workbooks
     def ensure_workbook(filename, options)  
-      filename = @stored_filename ? @stored_filename : filename
-      raise(FileNameNotGiven, 'filename is nil') if filename.nil?
-      if File.directory?(filename)
-        raise(FileNotFound, "file #{General.absolute_path(filename).inspect} is a directory")
-      end  
+      return if @ole_workook && alive?
+      filename = @stored_filename ? @stored_filename : filename 
       manage_nonexisting_file(filename,options)
-      workbooks = @excel.Workbooks
-      @ole_workbook = workbooks.Item(File.basename(filename)) rescue nil if @ole_workbook.nil?
-      if @ole_workbook
-        manage_blocking_or_unsaved_workbook(filename,options)
+      if RUBY_PLATFORM =~ /java/ && (options[:force][:excel].nil? || options[:force][:excel] == :current)
+        begin
+          connect(filename,options)  
+        rescue WorkbookConnectingNotAliveError
+          raise WorkbookNotSaved, "workbook is already open but not saved: #{File.basename(filename).inspect}"
+        rescue WorkbookConnectingBlockingError # can't find moniker
+          raise WorkbookBlocked, "can't open workbook #{filename}"+
+            "\nbecause it is being blocked by a workbook with the same name in a different path."
+        end
       else
-        open_or_create_workbook(filename, options)
+        workbooks = @excel.Workbooks
+        @ole_workbook = workbooks.Item(File.basename(filename)) rescue nil if @ole_workbook.nil?
+        if @ole_workbook
+          manage_blocking_or_unsaved_workbook(filename,options)
+        else
+          if options[:force][:excel].nil? || options[:force][:excel] == :current
+            connect(filename,options)
+          else 
+            open_or_create_workbook(filename,options)
+          end
+        end       
       end
+      set_options(options)
     end
 
   private
 
     # @private
-    def manage_nonexisting_file(filename,options)
+    # connects to an unknown workbook and returns true, if it exists
+    def connect(filename,options)
+      abs_filename = General.absolute_path(filename).tr('/','\\')
+      @ole_workbook = begin
+        WIN32OLE.connect(abs_filename)
+      rescue
+        raise WorkbookConnectingBlockingError
+      end
+      ole_excel = begin
+        WIN32OLE.connect(@ole_workbook.Fullname).Application 
+      rescue 
+        raise WorkbookConnectingNotAliveError
+      end
+      @excel = excel_class.new(ole_excel)
+    end
+
+    # @private
+    def manage_nonexisting_file(filename,options)      
       return if File.exist?(filename)
+      abs_filename = General.absolute_path(filename).tr('/','\\')
       if options[:if_absent] == :create
-        excel.Workbooks.Add
+        ensure_excel({:force[:excel] => :new}.merge(options)) if RUBY_PLATFORM !~ /java/
+        @excel.Workbooks.Add
         empty_ole_workbook = excel.Workbooks.Item(excel.Workbooks.Count)
-        abs_filename = General.absolute_path(filename).tr('/','\\')
         begin
           empty_ole_workbook.SaveAs(abs_filename)
         rescue # WIN32OLERuntimeError => msg
@@ -310,7 +324,7 @@ module RobustExcelOle
         manage_blocking_workbook(filename,options)        
       else
         unless @ole_workbook.Saved
-        # workbook open and writable, not obstructed by another workbook, but not saved
+          # workbook open and writable, not obstructed by another workbook, but not saved
           manage_unsaved_workbook(filename,options)
         end
       end        
@@ -320,12 +334,13 @@ module RobustExcelOle
     def manage_blocking_workbook(filename,options)
       case options[:if_obstructed]
       when :raise
-        raise WorkbookBlocked, "blocked by a workbook with the same name in a different path: #{@ole_workbook.Fullname.tr('\\','/')}" +
-        "\nHint: Use the option :if_obstructed with values :forget or :save,
-         to close the old workbook, without or with saving before, respectively,
-         and to open the new workbook"
+        raise WorkbookBlocked, "can't open workbook #{filename},
+        because it is being blocked by #{@ole_workbook.Fullname.tr('\\','/')} with the same name in a different path." +
+        "\nHint: Use the option :if_blocked with values :forget or :save,
+         to allow automatic closing of the old workbook (without or with saving before, respectively),
+         before the new workbook is being opened."
       when :forget
-        @ole_workbook.Close
+        @excel.with_displayalerts(false) { @ole_workbook.Close }
         @ole_workbook = nil
         open_or_create_workbook(filename, options)
       when :save
@@ -345,11 +360,12 @@ module RobustExcelOle
         @excel = excel_class.new(:reuse => false)
         open_or_create_workbook(filename, options)
       else
-        raise OptionInvalid, ":if_obstructed: invalid option: #{options[:if_obstructed].inspect}" +
+        raise OptionInvalid, ":if_blocked: invalid option: #{options[:if_obstructed].inspect}" +
         "\nHint: Valid values are :raise, :forget, :save, :close_if_saved, :new_excel"
       end
     end
 
+    # @private
     def manage_unsaved_workbook(filename,options)
       case options[:if_unsaved]
       when :raise
@@ -357,7 +373,7 @@ module RobustExcelOle
         "\nHint: Save the workbook or open the workbook using option :if_unsaved with values :forget and :accept to
          close the unsaved workbook and reopen it, or to let the unsaved workbook open, respectively"
       when :forget
-        @ole_workbook.Close
+        @excel.with_displayalerts(false) { @ole_workbook.Close }
         @ole_workbook = nil
         open_or_create_workbook(filename, options)
       when :accept
@@ -373,8 +389,6 @@ module RobustExcelOle
       end
     end
 
-  private
-
     # @private
     def open_or_create_workbook(filename, options)  
       if !@ole_workbook || (options[:if_unsaved] == :alert) || options[:if_obstructed]
@@ -404,18 +418,6 @@ module RobustExcelOle
             rescue WIN32OLERuntimeError => msg
               raise UnexpectedREOError, "WIN32OLERuntimeError: #{msg.message}"
             end
-            if options[:force][:visible].nil? && !options[:default][:visible].nil?
-              if @excel.created
-                self.visible = options[:default][:visible]
-              else
-                self.window_visible = options[:default][:visible]
-              end
-            else
-              self.visible = options[:force][:visible] unless options[:force][:visible].nil?
-            end
-            @ole_workbook.CheckCompatibility = options[:check_compatibility]
-            @excel.calculation = options[:calculation] unless options[:calculation].nil?
-            self.Saved = true # unless self.Saved # ToDo: this is too hard
           rescue WIN32OLERuntimeError => msg
             raise UnexpectedREOError, "WIN32OLERuntimeError: #{msg.message} #{msg.backtrace}"
           end
@@ -423,6 +425,23 @@ module RobustExcelOle
       end
     end
 
+    # @private
+    def set_options(options)
+      if options[:force][:visible].nil? && !options[:default][:visible].nil?
+        if @excel.created
+          self.visible = options[:default][:visible]
+        else
+          self.window_visible = options[:default][:visible]
+        end
+      else
+        self.visible = options[:force][:visible] unless options[:force][:visible].nil?
+      end      
+      @excel.calculation = options[:calculation] unless options[:calculation].nil?
+      @ole_workbook.CheckCompatibility = options[:check_compatibility]
+      @ole_workbook.Saved = true # unless self.Saved # ToDo: this is too hard
+    end
+           
+    # @private
     # translating the option UpdateLinks from REO to VBA
     # setting UpdateLinks works only if calculation mode is automatic,
     # parameter 'UpdateLinks' has no effect
@@ -435,6 +454,7 @@ module RobustExcelOle
       end
     end
 
+    # @private
     # workaround for linked workbooks for Excel 2007:
     # opening and closing a dummy workbook if Excel has no workbooks.
     # delay: with visible: 0.2 sec, without visible almost none
@@ -504,6 +524,7 @@ module RobustExcelOle
 
   private
 
+    # @private
     def close_workbook
       @ole_workbook.Close if alive?
       @ole_workbook = nil unless alive?
@@ -537,9 +558,9 @@ module RobustExcelOle
       unobtrusively(*args, &block)
     end
 
+
     # allows to read or modify a workbook such that its state remains unchanged
     # state comprises: open, saved, writable, visible, calculation mode, check compatibility
-    # remarks: works only for workbooks opened with RobustExcelOle
     # @param [String] file        the file name
     # @param [Hash]   opts        the options
     # @option opts [Variant] :if_closed  :current (default), :new or an Excel instance
@@ -557,7 +578,7 @@ module RobustExcelOle
       prefer_writable = ((!(opts[:read_only]) || opts[:writable] == true) &&
                          !(opts[:read_only].nil? && opts[:writable] == false))
       do_not_write = (opts[:read_only] || (opts[:read_only].nil? && opts[:writable] == false))
-      book = bookstore.fetch(file, :prefer_writable => prefer_writable)
+      book = bookstore.fetch(file, :prefer_writable => prefer_writable)    
       was_open = book && book.alive?
       if was_open
         was_saved = book.saved
@@ -746,7 +767,11 @@ module RobustExcelOle
     # closes a given file if it is open
     # @options opts [Symbol] :if_unsaved
     def self.close(file, opts = {:if_unsaved => :raise})
-      book = bookstore.fetch(file) rescue nil
+      book = begin
+        bookstore.fetch(file)
+        rescue
+          nil
+        end
       book.close(opts) if book && book.alive?
     end
 
@@ -758,7 +783,11 @@ module RobustExcelOle
 
     # saves a given file under a new name if it is open
     def self.save_as(file, new_file, opts = { })
-      book = bookstore.fetch(file) rescue nil
+      book = begin
+        bookstore.fetch(file)
+      rescue 
+        nil
+      end
       book.save_as(new_file, opts) if book && book.alive?
     end
 
@@ -807,11 +836,12 @@ module RobustExcelOle
             sheet.Copy({ after_or_before.to_s => base_sheet.ole_worksheet })
           else
             @ole_workbook.Worksheets.Add({ after_or_before.to_s => base_sheet.ole_worksheet })
+            #@ole_workbook.Worksheets.Item(ole_workbook.Worksheets.Count).Activate
           end
         else
           # workaround for jruby      
           if after_or_before == :before 
-            if sheet 
+            if sheet
               sheet.Copy(base_sheet.ole_worksheet)
             else
               ole_workbook.Worksheets.Add(base_sheet.ole_worksheet)
@@ -835,10 +865,14 @@ module RobustExcelOle
             end
           end
         end
-      rescue WIN32OLERuntimeError 
-        raise WorksheetREOError, "given sheet #{sheet.inspect} not found"
+      rescue #WIN32OLERuntimeError 
+        trace "#{$!.message}"
+        raise WorksheetREOError, "could not add given worksheet #{sheet.inspect}"
       end
-      new_sheet = worksheet_class.new(@excel.Activesheet)
+      #ole_sheet = @excel.Activesheet
+      ole_sheet = ole_workbook.Activesheet
+      #ole_sheet = ole_sheet.nil? ? ole_workbook.Worksheets.Item(ole_workbook.Worksheets.Count) : ole_sheet
+      new_sheet = worksheet_class.new(ole_sheet)
       new_sheet.name = new_sheet_name if new_sheet_name
       new_sheet
     end
@@ -942,8 +976,10 @@ module RobustExcelOle
     end
 
     # makes both the Excel instance and the window of the workbook visible, or the window invisible
+    # does not do anything if geben visible_value is nil
     # @param [Boolean] visible_value determines whether the workbook shall be visible
     def visible= visible_value
+      return if visible_value.nil?
       @excel.visible = true if visible_value
       self.window_visible = visible_value
     end