spectools 1.0.0

data/CHANGELOG.txt

@@ -0,0 +1 @@
+1.0.0 - Initial release.

data/Manifest.txt

@@ -0,0 +1,80 @@
+TODO
+CHANGELOG.txt
+Manifest.txt
+README.txt
+README.vnmsh.txt
+Rakefile
+lib/spectools.rb
+lib/spectools/version.rb
+lib/vnmsh.rb
+test/data/connect.success
+test/data/create.alarm
+test/data/create.association
+test/data/create.model
+test/data/create.model.ip
+test/data/destroy.alarm
+test/data/destroy.association
+test/data/destroy.model
+test/data/seek
+test/data/seek.-s
+test/data/show.alarms
+test/data/show.alarms-a
+test/data/show.alarms-a-x
+test/data/show.alarms-x
+test/data/show.alarms.mh
+test/data/show.associations
+test/data/show.attributes
+test/data/show.attributes.attr
+test/data/show.attributes.attriid
+test/data/show.attributes.attrname
+test/data/show.attributes.attrr
+test/data/show.attributes.enum
+test/data/show.attributes.flags
+test/data/show.attributes.mth
+test/data/show.attributes.mth.attrr
+test/data/show.children
+test/data/show.children.rel
+test/data/show.devices
+test/data/show.enumerations
+test/data/show.enumerations.attr
+test/data/show.enumerations.mth
+test/data/show.events
+test/data/show.events-a
+test/data/show.events-n5
+test/data/show.events-x-n5
+test/data/show.inheritance
+test/data/show.landscapes
+test/data/show.models
+test/data/show.models.mhr
+test/data/show.models.mname
+test/data/show.models.mth
+test/data/show.parents
+test/data/show.relations
+test/data/show.rules
+test/data/show.types
+test/data/show.types.flags
+test/data/show.types.mthr
+test/data/show.types.mtname
+test/data/show.watch
+test/data/test.reconnect
+test/data/update.alarm
+test/data/update.model
+test/test_helper.rb
+test/test_spectools.rb
+test/test_vnmsh.rb
+test/testcmds/ack
+test/testcmds/connect
+test/testcmds/create
+test/testcmds/destroy
+test/testcmds/disconnect
+test/testcmds/seek
+test/testcmds/show
+test/testcmds/update
+test/vnmsh/ack
+test/vnmsh/connect
+test/vnmsh/create
+test/vnmsh/destroy
+test/vnmsh/disconnect
+test/vnmsh/seek
+test/vnmsh/show
+test/vnmsh/update

data/README.txt

@@ -0,0 +1,33 @@
+SpecTools is a toolset designed to make working with CA's SPECTRUM product (now Network Fault Manager) much easier. The base library represents the SPECTRUM data model: Models, Events, Alarms, Model Types, etc. All extra functionality is provided by extensions.
+
+Using the base SpecTools classes is very simple. Just require it!
+
+	require 'rubygems'
+	require 'spcetools'
+
+	model = SpecTools::Model.new
+	model.handle = 'test handle'
+
+All of the classes have good RDoc, so reference it to see what the structure looks like.
+
+Using Extensions.
+
+SpecTools has a very easy way of adding extra functionality to the library, called extensions.
+
+Using extensions.
+
+Using an extension is usually just a matter of requiring the object. For example, to use
+the CLI extenson, VNMSH, you would just:
+
+	require 'rubygems'
+	require 'spectools'
+	require 'vnmsh'
+
+Extensions extend the SpecTools by adding methods to the SpecTools classes. The methods all share
+a common prefix, which identifies the extension.`SpecTools has a config option,
+SpecTools::Config.default_access_method , that allows a user to determine what extension methods
+to use by default. For example, if SpecTools::Config.default_access_method = :cli , any method with
+a cli_ prefix will be available without needing to use the prefix. To continue the example, calling
+Model.find will automatically call Model.cli_find for you.
+
+Currently, the only available extension is VNMSH. You can read more about it in README.vnmsh. 

data/README.vnmsh.txt

@@ -0,0 +1,39 @@
+What is VNMSH?
+
+The VNMSH extension allows you to use SpecTools with the SPECTRUM
+CLI interface. With few exceptions, anything you can do with CLI,
+you can do with VNMSH. Also, the extension provides everything in
+SpecTools objects, not a flat strings or lines, so the data looks much
+more structures.
+
+Using the VNMSH Extension for SpecTools
+
+First, require both SpecTools and VNMSH:
+
+	require 'rubygems'
+	require 'spectools'
+	require 'vnmsh'
+
+Now, we'll establish a new VNMSH connection. If you have SPECROOT
+defined on the system, it is used, otherwise you'll need to pass
+it in:
+
+	session = VNMSH.new
+	session.connect
+
+You can now use any SpecTools method with a cli_ prefix. If you want
+to use VNMSH as you're default access method with SpecTools, set
+SpecTools::Config.default_access_method = :cli . This way, you won't 
+have to use the cli_ prefix when using VNMSH methods.
+
+All cli methods take a session as the last parameter. The session is 
+VNMSH session that you connected with. If you want to use a session
+and don't want to explictly pass it, you can simply assign your
+connected session to VNMSH.default session:
+
+	VNMSH.default_session = session
+
+Then you won't need to explictly pass a session over, however you can
+still override the default session by explictly passing it.
+
+Have fun using VNMSH!

data/Rakefile

@@ -0,0 +1,42 @@
+require 'rubygems'
+require 'fileutils'
+require 'hoe'
+include FileUtils
+require File.join(File.dirname(__FILE__), 'lib', 'spectools', 'version')
+
+AUTHOR = "Donavan Pantke"  # can also be an array of Authors
+EMAIL = "spectools-general@rubyforge.org"
+DESCRIPTION = "A utility suite for CA's SPECTRUM Network Fault Manager"
+GEM_NAME = "spectools" # what ppl will type to install your gem
+RUBYFORGE_PROJECT = "spectools" # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+
+
+NAME = "spectools"
+REV = nil # UNCOMMENT IF REQUIRED: File.read(".svn/entries")[/committed-rev="(d+)"/, 1] rescue nil
+VERS = ENV['VERSION'] || (Spectools::VERSION::STRING + (REV ? ".#{REV}" : ""))
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject { |x| Array(x).first == 'hoe' } 
+  end 
+end
+ENV['NODOT'] = '1'
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.author = AUTHOR 
+  p.description = DESCRIPTION
+  p.email = EMAIL
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.rdoc_pattern = /^(lib|bin)|txt|TODO$/
+
+#  p.clean_globs = CLEAN  #An array of file patterns to delete on clean.
+  
+  # == Optional
+  #p.changes        - A description of the release's latest changes.
+  #p.extra_deps     - An array of rubygem dependencies.
+  #p.spec_extras    - A hash of extra values to set in the gemspec.
+end

data/TODO

@@ -0,0 +1,5 @@
+TODO for version 1.1.0:
+- Create dispacther for use by AlarmNotifier.
+Future versions:
+- Create hooks to Southbound Gateway.
+- Create hooks to Modeling Gateway.

data/lib/spectools.rb

@@ -0,0 +1,588 @@
+#!/usr/bin/env ruby
+
+require 'stringio'
+
+# Copyright 2007 Donavan Pantke
+
+#SpecTools is a set of classes designed to help admins of CA's Spectrum perform common functions
+
+#We define here an extension to the String class to test if the string contains a valid Hex Code
+class String #:nodoc:
+	def hex?
+		!((self =~ /^0x[a-fA-F0-9]+$/).nil?)
+	end
+end
+
+# == Utility Module for SpecTools
+# The module defines some useful extensions that SpecTools utilizes.
+module SpecToolsExtensions
+
+	# This method allows extension developers to extend SpecTools without having to redefine stock methods.
+	# call_extension is usually invoked through method_missing or call_default_extension. It takes a method (in symbol form)
+	# and appends the prefix defined in SpecTools::Config.default_access_method .
+	# Example:
+	#
+	# <tt>call_extension(:get_attr,*args)</tt>
+	# 
+	# if SpecTools::Config.default_access_method is set to <tt>:access</tt>, call_extension will attempt call
+	# <tt>access_call_extension(*args)</tt>
+	# on itself, if the method is available. If the method does not exist, +NoMethodError+ is raised.
+	def call_extension(method,*args)
+		newmethod = SpecTools::Config.default_access_method.to_s + '_' + method.to_s
+		if self.respond_to?(newmethod.to_sym)
+			self.send(newmethod.to_sym, *args)
+		else
+			raise NoMethodError, "undefined method `#{newmethod}' for #{self}"
+		end
+	end
+
+	def method_missing(method, *args) #:nodoc:
+		if SpecTools::Config.default_access_method != nil
+			call_extension(method,*args)
+		else
+			super.method_missing
+		end
+	end
+
+	def self.method_missing(method, *args) #:nodoc:
+		if SpecTools::Config.default_access_method != nil
+			call_extension(method,*args)
+		else
+			super.method_missing
+		end
+	end
+	
+
+	# This method is explicitly called by the standard SpecTools object methods.
+	#
+	# Calls call_extension with the method sent.
+	#
+	# If <tt>SpecTools::Config.default_access_method</tt> is not set, <tt>SpecTools::NoAccessMethodError</tt> is raised.
+	def call_default_extension(method,*args)
+		if SpecTools::Config.default_access_method != nil
+			call_extension(method,*args)
+		else
+			raise SpecTools::NoAccessMethodError, 'In order to use this method, you must define Config::default_access_method'
+		end
+	end
+		
+end
+
+module SpecTools
+
+	
+	#Raised when SpecTools::Config.default_access_method is not set, and so the default accessor cannot be used.
+	class NoAccessMethodError < StandardError
+	end
+
+	#Raised when an attribute is assigned an incorrect value for its type. E.g. a list attribute is
+	#assigned a non-list value, or a non-list attribute is assigned a value_table. 
+	class InvalidValueTypeError < StandardError
+	end
+
+
+		
+
+
+	# == SpecTools::Config
+	# Contains module configuration.
+	class Config
+
+		class << self
+			#The default extension the data classes use when performing lookups. 
+			#The VNMSH extension defines the :cli access method.
+			attr_accessor :default_access_method
+		end
+
+	end
+
+	#  == SpecTools::Attr
+	#  Represents a Spectrum Attribute
+	class Attr
+
+		extend SpecToolsExtensions
+		include SpecToolsExtensions
+		
+		#The attribute ID
+		attr_accessor :id
+		#The attribute name
+	        attr_accessor :name
+		#The value of the attribute.
+		#Cannot be written to if the attribute is a list.
+		#If read from a list attribute, returns the first
+		#value from the list.
+		attr_accessor :value
+		#For list attributes, a hash of instance-value pairs.
+		#Can only be set if the attribute is a list attribute.
+	        attr_accessor :value_table
+		#A hash of the attribute's available enumerations
+		attr_accessor :enums
+		#The primitive type of the attribute
+	        attr_accessor :type
+		#Set to true if the attribute is external
+	        attr_accessor :external
+		#Set to true if the attribute is readable
+	        attr_accessor :readable
+		#Set to true if the attribute is writeable
+	        attr_accessor :writeable
+		#Set to true if the attribute is shared
+	        attr_accessor :shared
+		#Set to true if the attribute is a list attribute
+	        attr_accessor :list
+		#Set to true if the attribute is guaranteed
+	        attr_accessor :guaranteed
+		#Set to true of the attribute is global
+	        attr_accessor :global
+		#Set to true if the attribute is in memory
+	        attr_accessor :memory
+		#Set to true if the attribute is a database attribute
+	        attr_accessor :database
+		#Set to true if the attribute is polled
+	        attr_accessor :polled
+		#Set to true if the attribute is logged
+	        attr_accessor :logged
+		#Set to true if the attribute is preserved
+	        attr_accessor :preserve
+	
+		def initialize(id = nil, name = nil, value = nil, value_table = nil, enums = nil, list = false, type = nil, external = false, readable = false, writeable = false, shared = false, guaranteed = false, global = false, memory = false, database = false, polled = false, logged = false, preserve = false)
+			if id.nil? || id.hex?
+				@id = id
+			else
+				raise ArgumentError, "Id is not a hex code"
+			end
+			@name = name
+			@enums = enums
+			@type = type
+			@external = external
+			@readable = readable
+			@writeable = writeable
+			@shared = shared
+			@list = list
+			@guaranteed = guaranteed
+			@global = global
+			@memory = memory
+			@database = database
+			@polled = polled
+			@logged = logged
+			@preserve = preserve
+			if list
+				if value_table 
+					@value_table = value_table
+				else
+					value_table = Hash.new
+				end
+				@value = nil
+			else
+				@value_table = nil
+				@value = value
+			end
+		end
+
+		#Override the default writer for value. If the attr is a list , raise an error.
+		def value=(value) #:nodoc:
+			if list
+				raise InvalidValueTypeError, 'Attempt to set a list attribute to a non-list value'
+			else
+				@value = value
+			end
+		end
+
+		#Override the default writer for value_table. If the attr is a not a list, raise an error
+		def value_table=(value) #:nodoc:
+			unless list
+				raise InvalidValueTypeError, 'Attempt to set a regular attribute to a list value.'
+			else
+				@value_table = value
+			end
+		end
+
+		#Override the default value accessor. If we're a list attribute, return the first value in the list.
+		def value #:nodoc:
+			if list && value_table
+				@value_table[value_table.keys.sort.first]
+			elsif list
+				nil
+			else
+				@value
+			end
+		end
+
+		#Override the default list writer. Populate the appropriate value attribute.
+		def list=(list) #:nodoc:
+			if list
+				@value_table = Hash.new unless @value_table
+			end
+			@list = list
+		end
+
+
+		
+		#Look up the value of the given attribute and return its enumerated counterpart.
+		#If the Attr does not have a populated enums hash, will 
+		#attempt to use SpecToolsExtensions#call_default_extension to obtain the enumerations
+		#via the <tt>get_enums</tt> method. If enumeration fails, the original value
+		#is returned. All <tt>args</tt> are used for the call to <tt>get_enums</tt>, if
+		#necessary.
+		#<b>Note:</b> Errors raised by a call to get_enums will not be caught.
+		def enumerate(*args)
+			if enums.kind_of?(Hash)
+				avail_enums = enums
+			else
+				begin
+					avail_enums = call_default_extension(:get_enums, *args)
+				rescue NoAccessMethodError, NoMethodError
+					avail_enums = {}
+				end
+			end
+			if avail_enums[value]
+				return avail_enums[value]
+			else
+				return value
+			end
+
+		end
+			
+		#Change the value of the attribute to its enumerated string.
+		#If enumeration fails, the value is left unchanged.
+		#All arguments are passed through to enumerate.
+		def enumerate!(*args)
+			enum = enumerate(*args)
+			self.value = enum unless enum == value
+		end
+			
+			
+			
+	end
+
+	# == SpecTools::MType
+	# Represents a Spectrum model type
+	class MType
+
+		extend SpecToolsExtensions
+		include SpecToolsExtensions
+		
+		#The model type handle (mth)
+		attr_accessor :handle
+		#The model type's name
+		attr_accessor :name
+		#Set to true if the model type is visible
+		attr_accessor :visible
+		#Set to true if the model type can be instantiated
+		attr_accessor :instantiable
+		#Set to true if new model types can be derived from this one
+		attr_accessor :derivable
+		#Set to true if only one model of this type can exist
+		attr_accessor :unique
+		#Set to true if a model of the type must exist in the database
+		attr_accessor :required
+		#Set to true if models of this type can be destroyed
+		attr_accessor :destroyable
+		#An hash of Attr objects for this model type.
+		#When setting this attribute, you may either pass in a valid Hash
+		#or an Array of Attr objects
+		attr_accessor :attrs
+		#The type of inheritance
+		attr_accessor :inheritance
+		
+		def initialize(handle = nil, name = nil, attrs=Hash.new, visible = false, instantiable = false, derivable = false, destroyable = true, unique = false, required = false,inheritance = nil)
+			if  handle.nil? || handle.hex?
+				@handle = handle
+			else
+				raise ArgumentError, "Handle is not a hex code"
+			end
+			@name = name
+			@visible = visible
+			@instantiable = instantiable
+			@derivable = derivable
+			@destroyable = destroyable
+			@unique = unique
+			@required = required
+			@inheritance = inheritance
+			@attrs = populate(attrs)
+		end
+
+		#define a custom setter for attrs that will automatically convert
+		#an Array into a properly formatted hash.
+		def attrs=(new_attrs) #:nodoc:
+			if new_attrs.kind_of?(Hash)
+				@attrs = new_attrs
+			elsif new_attrs.kind_of?(Array)
+				@attrs = populate(new_attrs)
+			else
+				raise ArgumentError, 'attrs can only be assigned an Array or a Hash of Attr objects'
+			end
+		end
+
+		private
+		#Generate an attribute hash from an array
+		def populate(attrs)
+			attrs_hash = Hash.new
+			attrs.each do |specattr|
+				raise ArgumentError, 
+				      'The array can only contain SpecTools::Attr objects' unless specattr.kind_of?(Attr)
+				attrs_hash[specattr.id] = specattr
+			end
+			attrs_hash
+		end
+
+				
+
+	end
+
+	# == SpecTools::Model
+	# Represents a Spectrum model
+	class Model
+
+		extend SpecToolsExtensions
+		include SpecToolsExtensions
+	
+		#The model's handle
+		attr_accessor :handle
+		#The model's name
+		attr_accessor :name
+		#The model's MType
+		attr_accessor :type
+		#A hash of Attr objects for the model
+		attr_accessor :attrs
+	
+		def initialize(handle = nil, name = nil, type = MType.new, *attrs)
+			if handle.nil? || handle.hex?
+				@handle = handle
+			else
+				raise ArgumentError, "Handle is not a hex code"
+			end
+			@name = name
+			@type = type
+			@attrs = Hash.new
+			attrs.each do |specattr|
+				if specattr.nil? || specattr.instance_of?(Attr)
+					@attrs[specattr.id] = specattr
+				else
+					raise ArgumentError
+				end
+			end
+				
+		end
+
+	end
+
+	# == SpecTools::Relation
+	# Represents a Spectrum relation
+	class Relation
+
+		extend SpecToolsExtensions
+		include SpecToolsExtensions
+
+		#The relation's name
+		attr_accessor :name
+		#This relation's type
+		attr_accessor :type
+		
+		def initialize(name = nil, type = nil)
+			@name = name
+			@type = type
+		end
+
+	end
+
+	# == SpecTools::Association
+	# Represents a Spectrum Association
+	class Association
+
+		extend SpecToolsExtensions
+		include SpecToolsExtensions
+		
+		#The Model on the left hand side of the association
+		attr_accessor :left_model
+		#The Model on the right hand side of the association
+		attr_accessor :right_model
+		#The Relation used for this association
+		attr_accessor :relation
+
+		def initialize(left_model = Model.new, right_model = Model.new, relation = Relation.new)
+			@left_model = left_model
+			@right_model = right_model
+			@relation = relation
+		end
+
+	end
+
+	# == SpecTools::Alarm
+	# Represents a Spectrum alarm
+	class Alarm
+
+		extend SpecToolsExtensions
+		include SpecToolsExtensions
+
+		#The alarm's ID
+		attr_accessor :id
+		#The time the alarm was generated.
+		#This time is local!  
+		attr_accessor :time
+		#The alarm's Probable Cause ID
+		attr_accessor :causeid
+		#The Model the alarm was asserted against
+		attr_accessor :model
+		#The alarm's severity
+		attr_accessor :severity
+		#Who the alarm is assigned to
+		attr_accessor :assignment
+		#The alarm's status
+		attr_accessor :status
+		#Set to true if the alarm has been acknowledged
+		attr_accessor :ack
+		#Set to true if the alarm is stale
+		attr_accessor :stale
+		#The Probable Cause text for the alarm
+		attr_accessor :message
+		#The URL for extra information about this alarm
+		attr_accessor :url
+		#The ticket number associated with this alarm
+		attr_accessor :ticket
+
+		def initialize(id = nil, time = nil, causeid = nil, model = Model.new, severity = nil, ack = false, stale = false, assignment = nil, status = nil, message = nil, url = nil, ticket = nil)
+			@id = id
+			@time = time
+			if causeid.nil? || causeid.hex?
+				@causeid = causeid
+			else
+				raise ArgumentError, "causeid is not a hex code."
+			end
+			if model.nil? || model.kind_of?(Model)
+				@model = model
+			else
+				raise ArgumentError, "model is not a Model object"
+			end
+			@severity = severity
+			@ack = ack
+			@stale = stale
+			@assignment = assignment
+			@status = status
+			@message = message
+			@url = url
+			@ticket = ticket
+		end
+
+		#Returns true if the alarm has been acknowledged
+		def ack?
+			@ack
+		end
+
+		#Returns true if the alarm is stale
+		def stale?
+			@stale
+		end
+
+		
+	end
+
+	# == SpecTools::Landscape
+	# Represents a Spectrum Landscape
+	class Landscape
+
+		extend SpecToolsExtensions
+		include SpecToolsExtensions
+		
+		#This landscape's SpectroSERVER
+		attr_accessor :ss
+		#The landscape's precedence
+		attr_accessor :precedence
+		#The SS port that the landscape is using
+		attr_accessor :port
+		#The landscape's service
+		attr_accessor :service
+		#The landscape's handle
+		attr_accessor :handle
+
+		def initialize(handle = nil, ssname = nil, precedence = nil, port = nil, service = nil )
+			@ss = ssname
+			@precedence = precedence
+			@port = port
+			@service = service
+			if handle.nil? || handle.hex?
+				@handle = handle
+			else
+				raise ArgumentError, "Handle is not a hex code"
+			end
+		end
+			
+	end
+
+	# == SpecTools::Event
+	# Represents a Spectrum event
+	class Event
+
+		extend SpecToolsExtensions
+		
+		#The time of the event
+		#This time is local!
+		attr_accessor :time
+		#The event's type (or Event ID)
+		attr_accessor :type
+		#The Model the event was asserted against
+		attr_accessor :model
+		#The event message
+		attr_accessor :message
+		
+		def initialize(time = nil, type = nil, model = Model.new, message = '')
+			@time = time
+			if type.nil? || type.hex?
+				@type = type
+			else 
+				raise ArgumentError, "Type is not a hex code."
+			end
+			@model = model
+			@message = message
+		end
+
+	end
+
+	# == SpecTools::Rule
+	# Represents a Spectrum Rule
+	class Rule
+
+		extend SpecToolsExtensions
+		include SpecToolsExtensions
+
+		#The MType on the left hand side of the rule
+		attr_accessor :left_mtype
+		#The MType on the right hand side of the rule
+		attr_accessor :right_mtype
+		
+		def initialize(left_mtype = MType.new, right_mtype = MType.new)
+			@left_mtype = left_mtype
+			@right_mtype = right_mtype
+		end
+		
+	end
+
+	# == SpecTools::Watch
+	# Represents a SpectroWATCH
+	class Watch
+		
+		extend SpecToolsExtensions
+		include SpecToolsExtensions
+
+		#The watch's ID (analogous to an Attr ID)
+		attr_accessor :id
+		#The watch's name
+		attr_accessor :name
+		#The watch's type
+		attr_accessor :type
+		#The watch's status
+		attr_accessor :status
+
+		def initialize(id = nil, name = nil, type = nil, status = nil)
+			@id = id
+			@name = name
+			@type = type
+			@status = status
+		end
+
+		
+	end
+
+end
+
+
+