rrt_ruby 0.2.1-mswin32 → 0.3.0-mswin32

data/lib/rrt_ruby/finder.rb

@@ -0,0 +1,264 @@
+RRT_DIR="rrt_ruby/" unless defined?(::RRT_DIR)
+require RRT_DIR+'classes'
+module RRT_RUBY
+	#This module defines the 'read' operations for a model.
+	#
+	#== Usage
+	#Using the Finder#find_logical_package, Finder#find_class, Finder#find_capsule (and the analogous component and deployment view calls) generates several OLE calls and possibly dulicate information.
+	#
+	#An example of creating duplicate information is using Finder#find_logical_package to access logical package A and then logical package B contained in A.
+	#
+	#The first call (accessing A) will return the LogicalPackage instance of A that already contains a LogicalPackage instance with the information of B.
+	#
+	#The second call will create a separate LogicalPackage instance with the information of B.
+	#
+	#It is recommended to always look for the top most package and then perform all operations using one of the LogicalPackage, ComponentPackage, DeploymentPackage classes.
+	#
+	#Moreover, the Finder#root_logical_package method caches the retrieved LogicalPackage instance, so subsequent calls do not generate further OLE calls.
+	#
+	#Finder#root_component_package, Finder#root_deployment_package etc. also do this for their respective Package instances.
+	module Finder
+		#Errors accessing the OLE Server are reported with this class
+		class FinderException<RuntimeError
+			attr_reader :modelname
+			def initialize modelname
+				super
+				@modelname=modelname
+			end
+		end
+		
+		TYPE_CLASS='Class'#OLE element type
+		TYPE_CAPSULE='Capsule'#OLE element type
+		TYPE_PROTOCOL='Protocol'#OLE element type
+		TYPE_LOGICAL_PACKAGE='LogicalPackage'#OLE element type
+		TYPE_DEPLOYMENT_PACKAGE='DeploymentPackage'#OLE element type
+		TYPE_COMPONENT_PACKAGE='ComponentPackage'#OLE element type
+		
+		#Returns the first OLE element with the given name, optionally if it's of the given type.
+		#
+		#Use the TYPE_ constants to define the element types
+		def ole_element name,type=nil
+			check
+			#get the simple  name
+			splitted=name.split("::")
+			simple_name=splitted[splitted.size-1] unless splitted.size==0
+			#find it
+			col=@model.FindModelElements(simple_name)
+			count=col.Count
+			1.upto(count){|i|
+				it=col.GetAt(i)
+				#match the first if no qualified name is given
+				if type
+					return it if it.IsClass(type)
+				else
+					return it
+				end if it&&name==simple_name&&it.Name==name
+				#match the qualified name
+				if type
+					return it if it.IsClass(type)
+				else
+					return it
+				end if it&&it.GetQualifiedName==name
+			}
+			@logger.warn("Element #{name} not found in #{@modelname}")
+			return nil
+		end
+		#This will return the logical view package matching the name or
+		#nil if no  package is found.
+		#
+		#If no fully qualified name is provided, then the first match is returned.
+		#
+		#Note that a package contains other packages and capsules and classes and this information is all read when calling this method
+		#so looking for a package high in the hierarchy can yield a structure containing most or all of the logical view of the model.
+		#
+		#Specifying "" or "LogicalView" as package_name will return the entire Logical View contents. See also LogicalFinder#root_package
+		def find_logical_package package_name
+			check
+			return root_logical_package if package_name=="" || package_name=="LogicalView"
+			el=ole_element(package_name,TYPE_LOGICAL_PACKAGE)
+			return LogicalPackage.new(el) if el
+			@logger.debug("Package #{package_name} not found in #{@modelname}") unless el
+			return nil
+		end
+		#Returns the first Capsule that matches the given name, nil if no match is made.
+		def find_capsule name
+			check
+			el=ole_element(name,TYPE_CAPSULE)
+			return Capsule.new(el) if el
+			@logger.debug("Capsule #{name} not found in #{@modelname}")
+			return nil
+		end
+		#Returns the RRT_RUBY::Class instance of the first class with the provided name 
+		#nil if nothing is found.
+		def find_class name
+			check
+			el=ole_element(name,TYPE_CLASS)
+			return RRT_RUBY::Class.new(el) if el
+			@logger.debug("Class #{name} not found in #{@modelname}")
+			return nil
+		end
+		
+		#Returns the LogicalPackage instance for Logical View. Essentially this instance contains the complete logical view contents
+		def root_logical_package
+			check
+			@logical_view=LogicalPackage.new(@model.RootLogicalPackage) unless @logical_view
+			return @logical_view
+		end
+		
+		#Returns the ComponentPackage instance for Component View. Essentially this instance contains the complete component view contents
+		def root_component_package
+			check
+			@component_view=ComponentPackage.new(@model.RootComponentPackage) unless @component_view
+			return @component_view
+		end
+		#Returns the DeploymentPackage instance for Deployment View. Essentially this instance contains the complete deployment view contents
+		def root_deployment_package
+			check
+			@deployment_view=DeploymentPackage.new(@model.RootDeploymentPackage) unless @deployment_view
+			return @deployment_view
+		end
+		
+		#Delivers all fully qualified component names under the defined package.
+		#If the parameter does not correspond to a component view package it will return an empty array
+		def component_names root_package
+			check
+			components=Array.new
+			#first of all find the package in the model
+			pkg= find_component_package(root_package)
+			begin 
+				comps=pkg.GetAllComponents
+				@logger.debug("There are #{comps.Count} components under #{pkg.GetQualifiedName}")
+				cnt=comps.Count
+				1.upto(cnt){|i|
+					components<<comps.GetAt(i).GetQualifiedName
+				}
+			end if pkg
+			return components
+		end
+		#Returns all components in the given package
+		def components root_package
+			check
+			components=Array.new
+			#first of all find the package in the model
+			pkg= find_component_package(root_package)
+			begin 
+				comps=pkg.GetAllComponents
+				@logger.debug("There are #{comps.Count} components under #{pkg.GetQualifiedName}")
+				cnt=comps.Count
+				1.upto(cnt){|i|
+					components<<Component.new(comps.GetAt(i))
+				}
+			end if pkg
+			return components
+		end
+		#Returns all executables in the given package
+		def executables root_package
+			check
+			components=Array.new
+			#first of all find the package in the model
+			pkg= find_component_package(root_package)
+			begin 
+				comps=pkg.GetAllComponents
+				@logger.debug("There are #{comps.Count} components under #{pkg.GetQualifiedName}")
+				cnt=comps.Count
+				1.upto(cnt){|i|
+					comp=comps.GetAt(i)
+					components<<Executable.new(comp) if comp.Type=~/Executable/
+				}
+			end if pkg
+			return components
+		end
+		#returns all libraries in the given package  and it's subpackages
+		def libraries root_package
+			check
+			components=Array.new
+			#first of all find the package in the model
+			pkg= find_component_package(root_package)
+			begin 
+				comps=pkg.GetAllComponents
+				@logger.debug("There are #{comps.Count} components under #{pkg.GetQualifiedName}")
+				cnt=comps.Count
+				1.upto(cnt){|i|
+					comp=comps.GetAt(i)
+					type=comp.Type
+					components<<Library.new(comp) if type=~/Library/ && !(type=~/External/)
+				}
+			end if pkg
+			return components
+		end
+		#Returns all external libraries in the given package and it's subpackages
+		def external_libraries root_package
+			check
+			comps=components(root_package)
+			return comps.collect{|c|
+				c if c.type=~/External/
+			}.compact
+		end
+		#This will return the first component package matching the name, nil if no component package is found.
+		#
+		#If no fully qualified name is provided, then the first match is returned
+		def find_component_package package_name=false
+			check
+			#get the simple package name
+			splitted=package_name.split("::")
+			simple_name=splitted[splitted.size-1] unless splitted.size==0
+			#get a collection with all the packages with the same name
+			col=@model.FindModelElements(simple_name)
+			count=col.Count
+			@logger.debug("There are #{count} packages named #{simple_name}")
+			1.upto(count){|i|
+				obj=col.GetAt(i)
+				#match the first if no qualified name is given
+				return obj if package_name==simple_name&&obj.Name==simple_name && obj.IsClass("ComponentPackage")
+				#match the qualified name
+				return obj if obj.GetQualifiedName==package_name && obj.IsClass("ComponentPackage")
+			}
+			return nil
+		end
+		#delivers all processors under the defined package.
+		#If the parameter does not correspond to a deployment view package it will return an empty array
+		def processors root_package
+			check
+			components=Array.new
+			#first of all find the package in the model
+			pkg= find_deployment_package(root_package)
+			begin 
+				comps=pkg.GetAllProcessors
+				$stdout.puts("There are #{comps.Count} processors under #{pkg.GetQualifiedName}") if debug
+				cnt=comps.Count
+				1.upto(cnt){|i|
+					components<<Processor.new(comps.GetAt(i))
+				}
+			end if pkg
+			return components
+		end
+		#This will return the first deployment package matching the name
+		#nil if no deployment package is found
+		#if no fully qualified name is provided, then the first match is returned
+		def find_deployment_package package_name
+			check
+			#get the simple package name
+			splitted=package_name.split("::")
+			simple_name=splitted[splitted.size-1] unless splitted.size==0
+			#get a collection with all the packages with the same name
+			col=@model.FindModelElements(simple_name)
+			count=col.Count
+			$stdout.puts "There are #{count} packages named #{simple_name}" if debug
+			1.upto(count){|i|
+				obj=col.GetAt(i)
+				#match the first if no qualified name is given
+				return obj if package_name==simple_name&&obj.Name==simple_name && obj.IsClass("DeploymentPackage")
+				#match the qualified name
+				return obj if obj.GetQualifiedName==package_name && obj.IsClass("DeploymentPackage")
+			}
+			return nil
+		end
+		private
+		#Checks to see if the Finder instance is valid
+		def check
+			raise FinderException.new(@modelname),"This Finder instance is invalid" unless @app
+			raise FinderException.new(@modelname),"Model not loaded" unless @model
+		end
+	end
+	
+end

data/lib/rrt_ruby/writer.rb

@@ -0,0 +1,166 @@
+RRT_DIR="rrt_ruby/" unless defined?(::RRT_DIR)
+require RRT_DIR+'finder'
+module RRT_RUBY
+	#This module defines the interface for write operations on a model.
+	#
+	#== Usage
+	#Due to the fact that the OLE interface throws several exceptions 
+	#when saving control units (when a control unit has changed in the filesystem, or when a control unit is contained in the unit that gets saved etc.) 
+	#and in gross violation of all things OO, RRTFinder#show is used to display the prompts to the user in order to avoid the exceptions.
+	#
+	#This is going to change, but at the moment the Writer module cannot be used to fully automate generation of models with multiple control units.
+	#
+	#Additionally at the moment, all _add_ operations fail miserably when the target package already exists
+	module Writer
+		include Finder
+		#Adds _package_ (a LogicalPackage instance) to the model.
+		#
+		#Throws a ModelException when something goes wrong.
+		#
+		#Things that can go wrong:
+		#
+		#* The parent package for _package_ does not exist
+		#* The parent package for _package_ is not writeable
+		def add_logical_package package,save=true
+			@logger.debug("Adding #{package.to_s}")
+			#if no parent it goes directly to logical view
+			if package.parent.empty?
+				host=@model.RootLogicalPackage 
+			else
+				#find if the parent exists
+				host=ole_element(package.parent,TYPE_LOGICAL_PACKAGE)
+			end
+			if host
+				if host.IsModifiable
+					#add the package
+					added_package=host.AddLogicalPackage(package.name)
+					added_package.stereotype=package.stereotype
+					#add all the classes
+					package.classes.each{|c|
+						add_class(c,added_package)
+					}
+					#add all the contained packages
+					package.packages.each{|p|
+						add_logical_package(p,false)
+					}
+					#save if wanted
+					begin
+						update_relations(package)
+						#show so that no errors are generated when dialogs pop up
+						self.show
+						#save, hide and invalidated the view cache
+						unit=host.GetContainingControlledElement
+						raise ModelException,"Could not save#{unit.name}" unless unit.Save
+						self.hide
+						@logical_view=nil
+					end if save
+				else
+					raise ModelException,"#{host.name} is not writable"
+				end
+			else
+				raise ModelException,"#{package.parent} does not exist in the model"
+			end
+		end
+		
+		#Removes a LogicalPackage from the model.
+		#
+		#Throws a ModelException when something goes wrong.
+		#Things that can go wrong:
+		#
+		#* The parent package for _package_ does not exist
+		#* _package_ does not exist
+		#* The parent package for _package_ is not writeable
+		def remove_logical_package package
+			@logger.debug("Removing #{package.to_s}")
+			#if no parent it goes directly to logical view
+			if package.parent.empty?
+				host=@model.RootLogicalPackage
+				@logger.debug("...from the root logical package")
+			else
+				#find if the parent exists
+				host=ole_element(package.parent,TYPE_LOGICAL_PACKAGE)
+			end
+			if host
+				if host.IsModifiable
+					pkg=ole_element(package.qualified_name,TYPE_LOGICAL_PACKAGE)
+					if pkg
+						self.show
+						#delete the package
+						host.DeleteLogicalPackage(pkg)
+						unit=host.GetContainingControlledElement
+						raise ModelException,"Could not save#{unit.name}" unless unit.Save
+						self.hide
+						@logical_view=nil
+					else
+						@logger.info("#{package.name} does not exist in the model") 
+					end
+				else
+					raise ModelException,"#{host.name} is not writable"
+				end
+			else
+				raise ModelException,"#{package.parent} does not exist in the model"
+			end
+		end
+		
+		#Checks if an OLE element with the given name can be written to/is modifiable
+		#
+		#Raises a ModelException if no element is found
+		def writeable? name
+			el=ole_element(name)
+			if el
+				return el.IsModifiable
+			else
+				raise ModelException,"#{name} does not exist in the model"
+			end
+		end
+		
+		private
+		#Adds _c_ to the OLE _package_element_
+		def add_class c,package_element
+			added=package_element.AddClass(c.name)
+			added.stereotype=c.stereotype
+		end
+		#Adds _c_ to the OLE _package_element_
+		def add_capsule c,package_element
+			added=package_element.AddCapsule(c.name)
+		end
+		
+		
+		#Updates all elements contained in OLE _package_ 
+		#with the proper relations
+		def update_relations package
+			package.all_classes.each{|c|
+				add_relations_to_element(c)
+			}
+			package.all_protocols.each{|c|
+				add_relations_to_element(c)
+			}
+			package.all_capsules.each{|c|
+				add_relations_to_element(c)
+			}
+		end
+		#Finds the OLE element corresponding to _c_ and creates the relations 
+		#using the Relation instances of _c_
+		def add_relations_to_element c
+			el=ole_element(c.qualified_name)
+			if el
+				c.relations.each{|r|
+					begin
+						case r.relation_type
+							when Relation::CLASS
+								el.AddClassDependency("",r.supplier)
+							when Relation::COMPONENT
+							when Relation::PACKAGE
+							when Relation::GENERALIZATION
+							when Relation::REALIZE
+						end
+					rescue
+						@logger.warn("Could not add dependency: #{$!}")
+					end
+				}
+			else
+				@logger.warn("Element #{c.qualified_name} not found")
+			end
+		end
+	end
+end

data/lib/rrt_ruby.rb

@@ -1,25 +1,39 @@
 #rrt_ruby is a library that provides access to Rational Rose RealTime models through RRTEI (The Rose Real Time Extensibility Interface).
-#In order to use it, you need a valid RoseRT license.
+#In order to use it, you need a valid RoseRT license (and only because you can'T start RoseRT otherwise).
 #
 #For more information look at RRT_RUBY
 
 #
 RRT_DIR="rrt_ruby/" unless defined?(::RRT_DIR)
-require RRT_DIR+'rrt_logical'
-require RRT_DIR+'rrt_deployment'
-require RRT_DIR+'rrt_component'
+require RRT_DIR+'finder'
+require RRT_DIR+'writer'
+require RRT_DIR+'classes'
+
 #== Synopsis
 #The RRT_RUBY module provides the namespace for the rrt_ruby library.
 #
-#The library defines a set of objects that correspond to model elements and the RRTFinder class that provides a way of querying a model.
-#
+#The library defines a set of objects that correspond to model elements, the RRTFinder class as a read-only interface for the model and the RRTAccessor class
+#as a read-write interface for the model.
 #
 #== Usage
-#The following code will return a LogicalPackage instance representing the requested package containing all capsules, classes and packages thereof.
-##The backslashes are vital - '/' won't work because we are making an OLE call and RoseRT doesn't understand paths with '/'.
-# RRTFinder.open("path\\name\\to\\model.rtmdl"){|finder|
-#	finder.find_logical_package("Package")
-# }
+#Since version 0.3 rrt_ruby offers a package based way of working with RRT models:
+#
+#UseCasePackage for accessing use case view elements
+#
+#LogicalPackage for accessing logical view elements
+#
+#ComponentPackage for accessing component view elements
+#
+#DeploymentPackage for accessing deployment view element
+#
+#The top most element of every view is the root package for every view, which means that Finder#root_logical_package will return a LogicalPackage instance containing the complete logical view.
+#
+#Finder#root_component_package will return a ComponentPackage instance with the complete component view and so on.
+#
+#Once a package element is extracted into the corresponding Package instance, the contents can be searched/altered without resorting to OLE calls.
+#
+#This provides us with a significant performance advantage.
+#
 #
 #== Author
 # Vassilis Rizopoulos
@@ -27,7 +41,7 @@ require RRT_DIR+'rrt_component'
 #== Changelog
 # Created: 28.09.2005
 #
-# Last modified: 28.09.2005 by damphyr
+# Last modified: 19.10.2005 by riva
 #
 #== Copyright
 # Copyright (c) 2005 Vassilis Rizopoulos
@@ -36,11 +50,140 @@ require RRT_DIR+'rrt_component'
 public
 module RRT_RUBY
 	VERSION_MAJOR='0'
-	VERSION_MINOR='2'
-	#RRTFinder aggregates the RRTLogical, RRTComponent and RRTDeployment modules to provide access to all views of a RoseRT model (ok, ok, RRTUseCase is missing)
-	class RRTFinder<RRTGeneric::Finder
-		include RRTLogical::LogicalFinderModule
-		include RRTComponent::ComponentFinderModule
-		include RRTDeployment::DeploymentFinderModule
+	VERSION_MINOR='3'
+	require 'win32ole'
+	require 'riva_ruby'
+	OLEAPP_NAME='RoseRT.Application'
+	
+	#RRTFinder provides the primary interface for read-only access of RRT models using OLE Automation.
+	#
+	#It will create an OLE instance of RRT on initialization.
+	#
+	#In order to properly release this instance RRTFinder#stop must be called prior to exiting 
+	#the Ruby application.
+	#
+	#Alternatively RRTFinder#open can be used with a block.
+	#
+	#RRT under Windows XP (not tested on other versions) only allows three instances. Unfortunately, once an OLE Automation instance
+	#is accessed, references prevent the instances from being destroyed even after stopping RRTFinder.
+	#
+	#This effectively limits the number of possible RRTFinder instances per application to three.
+	#
+	#Notice that you still need to call stop or use open with a block otherwise the RRT
+	#application will remain in memory after termination of the Ruby application.
+	#
+	#See the Finder module for a description of the actual read interface.
+	class RRTFinder
+		include RivaLib::RivaLogger
+		include Finder
+		attr_reader :modelname, :model
+		#Initialize will throw an exception if the model cannot be opened.
+		#
+		#RRTFinder uses Logger to log on STDOUT. Optionally you can pass a Logger instance
+		#and it will be used.
+		def initialize modelname="",logger=nil
+			logger_init(logger)
+			@modelname=modelname
+			@logger.debug("Opening model #{@modelname}")
+			@app=WIN32OLE.new(OLEAPP_NAME)
+			@model=@app.OpenModel(@modelname) unless modelname.empty?
+			raise FinderException.new(@modelname),"Model not loaded" unless @model
+		end
+		#open is used in conjuction with a block.
+		#
+		#It creates a RRTFinder instance and passes it to the block. 
+		#At the end of the block the RRTFinder is stopped and invalidated.
+		#
+		#You can optionally pass a Logger instance to be used by the RRTFinder.
+		#
+		#Without a block the method is just an alias for RRTFinder#new
+		
+		def self.open modelname,logger=nil #:yields: self
+			begin
+				fndr=self.new(modelname,logger)
+				if block_given?
+					begin
+						yield fndr
+					ensure
+						fndr.stop
+					end
+				else
+					return fndr
+				end
+			end
+		end
+		#Instructs the RRTFinder to load a new model into it's associated RRT instance.
+		#
+		#If modelname matches the current modelname or the RRTFinder is invalid...well, nothing will happen.
+		def reload modelname
+			begin 
+				@modelname=modelname
+				@model=@app.openmodel(@modelname)
+				raise FinderException.new(@modelname),"Model not loaded" unless @model
+			end if @app && @app.CurrentModel.GetFileName.upcase!=modelname.upcase
+		end
+		#Stops the RRTFinder releasing the OLE interface and invalidating this RRTFinder instance.
+		#
+		#This method *must* be called to clean up resources unless you used RRTFinder#open with a block. 
+		#
+		#If you don't call this method you will end up with a zombie RoseRT instance and a couple of MBs less memory.
+		#
+		#After calling stop the RRTFinder instance cannot be used again (most methods throw a FinderException).
+		#
+		#Unfortunately, there is no control on when the RRT instance is going to exit.
+		#
+		#Usually RRT instances that have been accessed will not exit until the application/script ends.
+		#Since RRT only allows three running instances, this means you can only reload a stopped finder twice.
+		def stop
+			@logger.debug("Stopping Finder")
+			@app.exit if @app
+			@app.ole_free()
+			@model=nil
+			@app=nil
+		end
+		#Shows the RRT UI for the associated OLE instance
+		#Makes the RRT UI associated with the RRTFinder visible.
+		#
+		#Throws a FinderException if no instance exists
+		def show
+			raise FinderException.new(@modelname),"This Finder instance is invalid" unless @app
+			@app.visible=true
+		end
+		#Hides the RRT UI for the associated OLE instance.
+		#
+		#Throws a FinderException if no instance exists
+		def hide
+			raise FinderException.new(@modelname),"This Finder instance is invalid" unless @app
+			@app.visible=false
+		end
+		#Returns the name of the model with which the RRTFinder is connected
+		#
+		#Alias for Finder#modelname
+		def name
+			return @modelname
+		end
+		def to_s
+			return "Active on #{@modelname}" if @model
+			return "Invalid for #{@modelname}"
+		end
+	end
+	
+	
+	
+	#Returns the pathname for the current model if an OLE server is present, nil otherwise
+	def self.current_model
+		begin
+			rt = WIN32OLE.connect(OLEAPP_NAME)
+			return rt.CurrentModel.GetFileName
+		rescue
+			return nil
+		end
+	end
+	
+	#Provides read/write access to a RoseRT model
+	#
+	#See Writer for the 'write' interface
+	class RRTAccessor<RRTFinder
+		include Writer
 	end
 end

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.3
 specification_version: 1
 name: rrt_ruby
 version: !ruby/object:Gem::Version 
-  version: 0.2.1
-date: 2005-10-13
+  version: 0.3.0
+date: 2005-10-19
 summary: rrt_ruby is a Ruby library providing access to Rose RealTime models through RRTEI
 require_paths: 
   - lib
@@ -29,10 +29,9 @@ authors:
 files: 
   - lib/riva_ruby.rb
   - lib/rrt_ruby.rb
-  - lib/rrt_ruby/rrt_component.rb
-  - lib/rrt_ruby/rrt_deployment.rb
-  - lib/rrt_ruby/rrt_generic.rb
-  - lib/rrt_ruby/rrt_logical.rb
+  - lib/rrt_ruby/classes.rb
+  - lib/rrt_ruby/finder.rb
+  - lib/rrt_ruby/writer.rb
 test_files: []
 rdoc_options: []
 extra_rdoc_files: []