net-tnsping 1.0.0

data/CHANGES

@@ -0,0 +1,39 @@
+== 1.0.0 - 7-Jun-2005
+* Moved project to RubyForge.
+* Added a .gemspec file.
+* Bumped the VERSION number.
+* Inlined some rdoc code into tnsping.rb.
+
+== 0.2.1 - 18-Apr-2005
+* Fixed a bug in the tnsnames.ora parser method for those cases where each
+  db entry is on its own line.
+* Corrected the date of the last release, and added the 0.1.1 and 0.1.2
+  changes back into the CHANGES file.
+
+== 0.2.0 - 12-Apr-2005
+* Massive internal refactoring.
+* No longer requires that each tnsnames.ora entry be on its own line.
+* Much improved documentation.
+* Moved the sample program to the 'examples' directory.
+* Many more tests added.
+* Removed the INSTALL file.  Installation instructions are now included in
+  the README file.
+* The README and CHANGES files are now rdoc friendly.
+
+== 0.1.2 - 11-Apr-2003
+* Fixed a regex bug in the parse_tns_file() method that could cause problems
+  retrieving the correct host and/or port.
+* Fixed the testsuite up a bit.
+
+== 0.1.1 - 20-Mar-2003
+* The default domain/zone from the sqlnet.ora file are automatically appended
+  to the check against the tnsnames.ora file (if present).
+* Slightly better internal error handling added
+* Added VERSION constant and class method
+* Some more assertions added, and some minor changes, to the test suite
+* rd2 documentation separated from source - now in /doc directory
+* Changed CHANGELOG to CHANGES (merely for consistency with my other packages).
+* Doc updates
+
+== 0.1.0 - 19-Dec-2002
+* Initial Release

data/MANIFEST

@@ -0,0 +1,11 @@
+CHANGES
+MANIFEST
+README
+install.rb
+net-tnsping.gemspec
+
+examples/test_tnsping.rb
+
+lib/net/tnsping.rb
+
+test/tc_tns_ping.rb

data/README

@@ -0,0 +1,189 @@
+== Description
+   This package emulates the Oracle tnsping utility.
+
+== Prerequisites
+   Ruby 1.8.0 or later
+   dbi
+   net-pingsimple 0.3.1 or later
+   Any of the Oracle database drivers (oracle, oci8, ruby9i, etc)
+   
+== Installation
+
+=== Manual Installation
+   ruby test/tc_tns_ping.rb (optional)
+   ruby install.rb
+   
+=== Gem Installation
+   ruby net-tnsping.gemspec
+   gem install net-tnsping-<version>.gem
+	
+=== Installation Note
+   You will have to manually tweak one instance variable (@db) in the
+   test suite in order to get all tests to pass.  Set it to a known database
+   name.
+
+== Synopsis
+   require "net/tnsping"
+   include Net
+
+   t = TNSPing.new("my_db")
+
+   if t.ping?
+      puts "Database appears to be up and running"
+   else
+      puts "There was a problem: " + t.exception
+   end
+
+== Constants
+VERSION
+   The version number of this package, returned as a String.
+
+== Class Methods
+TNSPing.new(db, driver="OCI8", host=nil, port=1521, timeout=5)   
+   Creates and returns a new TNSPing object.  If the db specified cannot be
+   found in the tnsnames.ora file, then a TNSPingError is raised.
+
+== Instance Methods
+TNSPing#db
+   Returns the name of the database that the TNSPing#ping_database? method
+   will attempt to connect to.
+
+TNSPing#db=(database)
+   Sets the name of the database that the TNSPing#ping_database? method
+   will attempt to connect to.
+
+TNSPing#driver
+   Returns the name of the driver used by the TNSPing#ping_database? method.
+   The default is OCI8.
+
+TNSPing#driver=(driver)
+   Sets the name of the driver used by the TNSPing#ping_database? method.
+
+TNSPing#dsn
+   Returns the dsn string that is used by TNSPing#ping_database?.
+
+TNSPing#dsn=(string)
+   Sets the dsn string that is used by TNSPing#ping_database?.  It should
+   be in the form "dbi:driver:database".
+
+TNSPing#host
+   Returns the host that the TNSPing#ping_listener? call will use.  This may
+   be nil, in which case, the TNSPing#hosts method will list which hosts it
+   will attempt to ping.
+
+TNSPing#host=(host)
+   Sets the host that the TNSPing#ping_listener? call will use.  If this is
+   set, then a ping will only be attempted against this host, irregardless
+   of what is in the tnsnames.ora file.
+
+TNSPing#oracle_home
+   Returns the path to the oracle home directory.  The default is either
+   ENV["ORACLE_HOME"] or ENV["ORA_HOME"].
+
+TNSPing#oracle_home=(path)
+   Sets the path to the oracle home directory.
+
+TNSPing#ping?
+TNSPing#ping_listener?
+   Performs a TCP ping on the listener. The host and port are determined from
+   your tnsnames.ora file. If more than one host and/or port are found in the
+   tnsnames.ora file, then each will be tried.  So long as at least one of
+   them connects successfully, true is returned. 
+
+   If you specify a host and port in the constructor, then the attempt will
+   only be made against that host on the given port.
+
+TNSPing#ping_database?(dsn=nil, timeout=nil, user=nil, passwd=nil)
+   Attempts to make a connection using a bogus login and password via the DBI
+   class.  If an ORA-01017 Oracle error is returned, that means the database
+   is up and running and true is returned.
+
+   Note that each of the arguments for this method use the defaults passed
+   to the constructor (or have a default otherwise set).  You generally
+   should not pass any arguments to this method.
+
+   In the event that this method fails, false is returned and the error can
+   be viewed via TNSPing#exception.
+
+TNSPing#ping_all?
+   A shortcut method that merely calls TNSPing#ping? and TNSPing#ping_database? 
+   in succession.  Returns true if both succeed, false otherwise.
+
+TNSPing#port
+   Returns the port that the TNSPing#ping_listener? will ping against.  This
+   may be nil, in which case the TNSPing#ports method will list which ports
+   it will attempt to ping against.
+
+TNSPing#port=(num)
+   Sets the port that the TNSPing#ping_listener? method will use.  If this is
+   set, then a ping will only be attempted on this port, irregardless of what
+   is in the tnsnames.ora file.
+
+TNSPing#timeout
+   Returns the timeout value used by all internal ping methods.
+
+TNSPing#timeout=(seconds)
+   Sets the timeout used by all internal ping methods.
+
+TNSPing#tns_admin
+   Returns the path to the tns admin directory.  The default is
+   ENV["TNS_ADMIN"].
+
+TNSPing#tns_admin=(path)
+   Sets the path to the tns admin directory.
+
+TNSPing#tns_file
+   Returns the full path to the tnsnames.ora file.
+
+TNSPing#tns_file=(path)
+   Sets the path to the tnsnames.ora file.
+
+== Notes
+   The TNSPing class is a subclass of PingTCP.
+
+   This is NOT a wrapper for the tnsping utility.  It performs two actions.
+   First, it attempts to ping the database using the appropriate port via TCP.
+   Then, it attempts to make a connection using a bogus name and password,
+   looking for error ORA-1017.
+
+== Potential Questions
+   Q: "Why didn't you just wrap a backticked tnsping call?"
+
+   A: First, because the output is unpredictable. On two different platforms I
+   received two different output streams for the same datasource.  Who knows
+   what it's like on other platforms?
+
+   Second, tnsping *only* tells you if the listener is up.  It doesn't
+   actually test that the datasource is up and running.
+
+   Q: "Why didn't you write an extension using the tnsping source?"
+
+   A: Because the source is closed. One Oracle DBA told me that even attempting
+   to reverse-engineer the source was prohibited and that I should quit wasting
+   my time.  Well, I wasted my time anyway, and came up with an even better and
+   more reliable solution.
+
+== Known Bugs
+   None that I'm aware of.  Please log any bug reports on the project page
+   at http://www.rubyforge.org/projects/shards
+
+== Acknowledgements
+   Thanks go to Bryan Stanaway, a colleague and Oracle DBA who helped me out
+   with some questions I had.
+
+== Copyright
+   (C) 2003-2005 Daniel J. Berger
+   All rights reserved.
+	
+== Warranty
+   This package is provided "as is" and without any express or
+   implied warranties, including, without limitation, the implied
+   warranties of merchantability and fitness for a particular purpose.
+	
+== License
+	Ruby's
+
+== Author
+   Daniel J. Berger
+   djberg96 at yahoo dot com
+   imperator on IRC (irc.freenode.net)

data/lib/net/tnsping.rb

@@ -0,0 +1,205 @@
+require "dbi"
+require "net/pingsimple"
+
+module Net
+   class TNSPingError < StandardError; end
+   class TNSPing < PingTCP
+
+      VERSION = "1.0.0"
+
+      attr_accessor :db, :dsn, :tns_file, :host, :tns_admin
+      attr_accessor :oracle_home, :driver, :timeout
+      attr_reader :hosts, :ports, :port
+
+      # Creates and returns a new TNSPing object.  If the db specified cannot
+      # be found in the tnsnames.ora file, then a TNSPingError is raised.
+      #
+      def initialize(db, driver="OCI8", host=nil, port=1521, timeout=5)
+         @db        = db
+         @dsn       = "dbi:#{driver}:" << db
+         @timeout   = timeout
+         @port      = port
+         @tns_admin = tns_admin
+         @ports     = []  # There can be more than one host/port
+         @hosts     = []  # for each dsn.  Try them in order.
+         @sid       = nil
+
+         @tns_admin   = ENV["TNS_ADMIN"]
+         @oracle_home = ENV["ORACLE_HOME"] || ENV["ORA_HOME"]
+
+         if @tns_admin
+            @tns_file = @tns_admin + "/tnsnames.ora"
+         elsif @oracle_home
+            @tns_file = @oracle_home + "/network/admin/tnsnames.ora"
+         else
+            @tns_file = ENV["HOME"] + "/tnsnames.ora"
+         end
+
+         yield self if block_given?
+
+         # If the host is not specified, look for it in the tnsnames.or file
+         if host.nil?
+            err_msg = "tnsnames.ora file could not be found"
+            raise TNSPingError, err_msg unless File.exists?(@tns_file)
+            parse_tns_file
+         else
+            @hosts.push(host)
+            @ports.push(port)
+         end
+      end
+
+      # Sets the port that the TNSPing#ping_listener? method will use.  If
+      # this is set, then a ping will only be attempted on this port,
+      # regardless of what is in the tnsnames.ora file.
+      #
+      def port=(num)
+         @ports = [num]
+      end
+
+      # Performs a TCP ping on the listener. The host and port are determined from
+      # your tnsnames.ora file. If more than one host and/or port are found in the
+      # tnsnames.ora file, then each will be tried.  So long as at least one of
+      # them connects successfully, true is returned. 
+      #
+      # If you specify a host and port in the constructor, then the attempt will
+      # only be made against that host on the given port.
+      #--
+      # Try each host/port listed for a given entry.  Return a true result if
+      # any one of them succeeds and break out of the loop.
+      #
+      def ping?
+         if @hosts.empty?
+            raise TNSPingError, "No hosts found"
+         end
+
+         # Use 1521 if no ports were found in the tnsnames.ora file.
+         if @ports.empty?
+            @ports.push(@port)
+         end
+
+         # If the host is provided, only ping that host
+         if @host
+            0.upto(@ports.length-1){ |n|
+               @port = @ports[n]
+               return super
+            }
+         else
+            0.upto(@ports.length-1){ |n|
+               @port = @ports[n]
+               @host = @hosts[n]
+               return super
+            }
+         end
+      end
+
+      # Attempts to make a connection using a bogus login and password via the
+      # DBI class.  If an ORA-01017 Oracle error is returned, that means the
+      # database is up and running and true is returned.
+      #
+      # Note that each of the arguments for this method use the defaults
+      # passed to the constructor (or have a default otherwise set).  You
+      # generally should not pass any arguments to this method.
+      # In the event that this method fails, false is returned and the error
+      # can be viewed via TNSPing#exception.
+      #--
+      # I have intentionally set the user and password to something zany in
+      # order to avoid the possibility of accidentally guessing them.  In
+      # case of cosmic coincidence, set them yourself.
+      #
+      def ping_database?(dsn=@dsn, timeout=@timeout, user=@sid, passwd="xz949")
+         re   = /ORA-01017/
+         dbh  = nil
+         user ||= "pzoyadf244"
+         rv = false
+         begin
+            Timeout.timeout(timeout){
+               dbh = DBI.connect(dsn,user,passwd)
+            }
+         rescue DBI::DatabaseError => e
+            if re.match(e.to_s)
+               rv = true
+            else
+               @exception = e
+            end
+         rescue Timeout::Error, StandardError => e
+            @exception = e
+         ensure
+            if dbh
+               dbh.disconnect if dbh.connected?
+            end
+         end
+         rv
+      end
+
+      # Simple wrapper for ping_listener? + ping_database?
+      #
+      def ping_all?
+         return false unless self.ping_listener?
+         return false unless self.ping_database?
+         true
+      end
+
+      private
+
+      # parse_tns_file
+      #
+      # Search for the dsn entry within the tnsnames.ora file and get the host
+      # and port information.  Private method.
+      #
+      def parse_tns_file(file=@tns_file, db=@db)
+         re_blank      = /^$/
+         re_comment    = /^#/
+         re_tns_sentry = /^#{db}.*?=/                 # specific entry
+         re_tns_gentry = /^\w.*?=/                    # generic entry
+         re_tns_pair   = /\w+\s*\=\s*[\w\.]+/         # used to parse key=val
+         re_keys       = /\bhost\b|\bport\b|\bsid\b/i 
+
+         data_string = ""
+         found       = false
+
+         IO.foreach(file){ |line|
+            next if re_blank.match(line)
+            next if re_comment.match(line)
+            line.chomp!
+
+            # Skip over lines until an entry for the db is found.
+            match = re_tns_sentry.match(line)
+            if match
+               found = true
+               data_string << match.post_match # slurp the rest of the line
+               next
+            end
+
+            # Once found, slurp the lines into a variable until the next
+            # db entry is encountered.
+            if found
+               break if re_tns_gentry.match(line)
+               line.strip!
+               data_string << line
+            end
+         }
+
+         unless found
+            raise TNSPingError, "unable to find #{db} in #{file}"
+         end
+
+         # Break each 'key = value' line into its parts
+         data_string.scan(re_tns_pair).each{ |pair|
+            key, value = pair.split("=")
+            key.strip!
+            value.strip!
+            next unless re_keys.match(key)
+            case key.downcase
+               when "host"
+                  @hosts.push(value)
+               when "port"
+                  @ports.push(value.to_i)
+               when "sid"
+                  @sid = value
+            end
+         }
+      end
+
+      alias :ping_listener? :ping?
+   end
+end

data/test/tc_tns_ping.rb

@@ -0,0 +1,112 @@
+#########################################
+# tc_tns_ping.rb
+#
+# Test suite for the tns-ping package.
+#########################################
+base = File.basename(Dir.pwd)
+
+if base == "test" || base =~ /net-tnsping.*/
+   Dir.chdir("..") if base == "test"
+   $LOAD_PATH.unshift(Dir.pwd)
+   $LOAD_PATH.unshift(Dir.pwd + "/lib")
+end
+
+require "test/unit"
+require "net/tnsping"
+include Net
+
+# NOTE:
+# You'll need to change the db and host if you want to run these tests.
+
+class TC_TNSPing < Test::Unit::TestCase
+   def setup
+      @db = "changeme"
+      @tp = TNSPing.new(@db)
+   end
+   
+   def test_version
+      assert_equal("1.0.0", TNSPing::VERSION)
+   end
+
+   def test_db
+      assert_respond_to(@tp, :db)
+      assert_respond_to(@tp, :db=)
+      assert_nothing_raised{ @tp.db }
+      assert_equal(@db, @tp.db)
+   end
+
+   def test_dsn
+      assert_respond_to(@tp, :dsn)
+      assert_respond_to(@tp, :dsn=)
+   end
+
+   def test_port
+      assert_respond_to(@tp, :port)
+      assert_respond_to(@tp, :port=)
+      assert_equal(1521, @tp.port)
+   end
+
+   def test_ports
+      assert_respond_to(@tp, :ports)
+      assert_kind_of(Array, @tp.ports)
+      assert(@tp.ports.length > 0)
+   end
+
+   def test_host
+      assert_respond_to(@tp, :host)
+      assert_respond_to(@tp, :host=)
+   end
+
+   def tests_hosts
+      assert_respond_to(@tp, :hosts)
+      assert_kind_of(Array, @tp.hosts)
+      assert(@tp.hosts.length > 0)
+   end
+
+   def test_tns_file
+      assert_respond_to(@tp, :tns_file)
+      assert_respond_to(@tp, :tns_file=)
+      assert(File.exist?(@tp.tns_file))
+   end
+
+   def test_oracle_home
+      assert_respond_to(@tp, :oracle_home)
+      assert_respond_to(@tp, :oracle_home=)
+      assert_kind_of(String, @tp.oracle_home)
+   end
+
+   def test_tns_admin
+      assert_respond_to(@tp, :tns_admin)
+      assert_respond_to(@tp, :tns_admin=)
+   end
+
+   def test_ping_listener
+      assert_respond_to(@tp, :ping?)
+      assert_nothing_raised{ @tp.ping? }
+      assert_equal(true, @tp.ping?)
+   end
+
+   def test_ping_database
+      assert_respond_to(@tp, :ping_database?)
+      assert_nothing_raised{ @tp.ping_database? }
+      assert_equal(true, @tp.ping_database?)
+   end
+
+   def test_ping_all
+      assert_respond_to(@tp, :ping_all?)
+      assert_nothing_raised{ @tp.ping_all? }
+      assert_equal(true, @tp.ping_all?)
+   end
+
+   def test_bad_db
+      bad_db = "foo123bar"
+      assert_raises(TNSPingError){ TNSPing.new(bad_db) }
+      @tp.port = 9999
+      assert_equal(false, @tp.ping_listener?)
+   end
+
+   def teardown
+      @db   = nil
+      @tp   = nil
+   end
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.10
+specification_version: 1
+name: net-tnsping
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+date: 2005-06-07
+summary: A package for pinging Oracle listeners and databases
+require_paths: 
+- lib
+email: djberg96@gmail.com
+homepage: http://www.rubyforge.org/projects/shards
+rubyforge_project: 
+description: 
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+authors: 
+- Daniel J. Berger
+files: 
+- lib/net/tnsping.rb
+- CHANGES
+- MANIFEST
+- README
+- test/tc_tns_ping.rb
+test_files: 
+- test/tc_tns_ping.rb
+rdoc_options: []
+
+extra_rdoc_files: 
+- README
+- CHANGES
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+