place 0.1.0

data/Changelog

@@ -0,0 +1,11 @@
+2010-07-16 - Added memoization for total_on computing in WorkItem
+2010-07-14 - Added update* methods to Place: knowing where a repo is/was updated
+2010-06-25 - Tests refactored
+2010-06-25 - Added logging facility in collecting and retrieve
+2010-06-23 - Repository gathering reviewed, tests tuned.. and finally less code
+2010-06-21 - Added link workitems <-> projects
+2010-06-17 - Added links, watches and roles with testing
+2010-06-15 - Added comments with tests
+2010-06-15 - Added work record wirh testing
+2010-06-14 - Advanced on work_item testing
+2010-06-14 - Added users

data/LICENSE

@@ -0,0 +1,207 @@
+Copyright (c) 2010 Carlo Pecchia (info@carlopecchia.eu)
+
+This software is released under the condition of the Apache License:
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2010 Carlo Pecchia 
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

data/README.markdown

@@ -0,0 +1,96 @@
+
+Place is a Ruby library aimed to gather and manage objects from [Polarion ALM](http://www.polarion.com/)™ repositories. Its name comes from the contraction of "**P**olarion **lace**".
+
+
+# Intro
+
+**Place** collects informations from *Polarion ALM ™* and turns it into easy manageable ruby objects, which are managed by excellent key-value store [Redis](http://code.google.com/p/redis/), via the Ruby library [Ohm](http://ohm.keyvalue.org/).
+
+*Polarion &trade;* is an "Application Lifecycle Management" tool produced by *Polarion Software GmbH*. For more info on *Polarion ALM &trade;* please refers to <http://www.polarion.com/>.
+
+# Why?
+
+Basically I'd like to easy access to items inside a Polarion projects (namely "workitems"), as well as see relations among multiprojects workitems. That saved me a lot of time in extracting information and producing reports.
+
+
+# Examples
+
+First we need a local working copy of the repository. Notice we need only `.polarion` directories, not the WHOLE repository:
+
+	# obtain a local working copy of you Polarion repository
+	$ svn co http://your.polarion.server/repo/.polarion local_repo/.polarion
+	$ svn co http://your.polarion.server/repo/ProjectA/.polarion local_repo/ProjectA/.polarion
+	$ svn co http://your.polarion.server/repo/ProjectB/.polarion local_repo/ProjectB/.polarion
+	
+Then we go Ruby...
+
+
+## Gathering data 
+
+    require 'place'
+    include Place
+
+    Place.setup('./local_repo')
+    Place.logger_setup('/dev/null')
+  
+    Place.gather!
+    # This reset Redis db with a fresh new copy from the
+    # repository working copy (it's up to us update it).
+    # Of course is needed only when working copy is updated
+
+## Intro
+
+    require 'place'
+    include Place
+
+    Place.setup('./local_repo')
+    Place.logger_setup('/dev/null')
+
+    puts "Users: #{User.all.size}"
+    puts "Workitems: #{WorkItem.all.size}"
+
+    all_tasks = WorkItem.find_by_type(:task)
+  
+    demo = Project.find_by_name('Demo')
+	demo_tasks = demo.workitems(:type => :taks)
+  
+    t = demo_tasks.last
+    puts "Assignees for #{t.wid}: #{t.assignees.map{|u| u.name}.join(' ')}"
+
+  
+## Assigned tasks
+
+    require 'place'
+    include Place
+
+    Place.setup('./local_repo')
+    Place.logger_setup('/dev/null')
+
+    tasks = WorkItem.fnid_by_type(:task)
+    assigned_tasks = tasks.reject{|wi| wi.assignees.empty? }
+    assigned_tasks.each do |wi|
+      puts "#{wi.wid} assigned to #{wi.assignees.map{|u| u.name}.join(' ')}"
+    end
+
+
+## Limitations
+
+* **Place** does *not* work with LiveDocument workitems, that are workitems stored in Microsoft document rather than .xml files.
+* The actual version was tested under *Linux* and *Mac OS X* only.
+
+## Performance
+
+Retrieving data from a repository working copy takes not too much time. Assuming the time required grows with the numbers of workitems, we experienced a total retrieve time of 60 seconds with 1700 workitems.
+
+## Roadmap
+
+* add more examples into documentation
+* add hyperlinks for workitems (and votes, approvals, ...)
+* (maybe) incremental update rather than one-shot gathering
+* implement write back to repository
+* callback for each workitem type (es: complex calculated fields)
+
+	
+## Author
+
+Place is written by [Carlo Pecchia](mailto:info@carlopecchia.eu) and released under the terms of Apache License (see LICENSE file).

data/Rakefile

@@ -0,0 +1,9 @@
+
+require 'rake/testtask'
+
+desc "Run tests"
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/test_*.rb']
+end
+
+task :default => [:test]

data/Technical.markdown

@@ -0,0 +1,29 @@
+# Technical Info
+
+## Ratio
+
+Polarion ™ stores data under a [Subversion](http://subversion.apache.org/) repository - located on the server it runs on - encoded in XML files at two levels:
+
+* Global level:
+  - .polarion/user-management/users/<name>/user.xml
+* Project level:
+  - <prj>/.polarion/tracker/timepoints/<tid>.xml
+  - <prj>/.polarion/security/user-roles.xml
+  - <prj>/.polarion/tracker/workitems/**/<wid>/workitem.xml
+  - <prj>/.polarion/tracker/workitems/**/<wid>/workrecord-<N>.xml
+  - <prj>/.polarion/tracker/workitems/**/<wid>/comment-<N>.xml
+
+	
+## Collecting & Retrieving sequence
+
+In order to correctly build the "graph" of entities (work items, comments, work records, users, etc) we have to define a strict retrieve sequence:
+
+	projects
+	users
+	for each project:
+		timepoints
+		workitems
+			author, assignees, links, comments, workrecords
+		users' roles
+		users' watches
+

data/examples/sample-1.rb

@@ -0,0 +1,34 @@
+
+require 'rubygems'
+require 'place'
+
+include Place
+
+# this path refers to (root) repository local working copy
+Place.setup('../test/repo')
+
+Place.logger_setup('/dev/null')
+
+# that is not necessary each time!
+Place.gather!
+
+puts "Retrieved #{Project.all.size} projects."
+puts "Retrieved #{WorkItem.all.size} workitems."
+
+tasks = WorkItem.find_by_type :task
+puts "  tasks: #{tasks.size}"
+
+puts "-" * 60
+
+# for each task print: ID, title and list of linked in workitems
+tasks.each do |t|
+  printf("[%4s] - %-10s (%s)\n", t.wid, t[:title], t.links_in.map{|l| l.from.wid}.join(', '))
+end
+
+puts "-" * 60
+
+# do the same, but only in a project context
+p = Project.find_by_name('P')
+p.workitems(:type => :taks).each do |t|
+  printf("[%4s] - %-10s (%s)\n", t.wid, t[:title], t.links_in.map{|l| l.from.wid}.join(', '))
+end

data/lib/place/comment.rb

@@ -0,0 +1,76 @@
+module Place
+
+# Each Comment belongs to a WorkItem and is written by a User
+class Comment < Ohm::Model
+  attribute :url
+  index :url
+  
+  attribute :title
+  attribute :created
+  attribute :text
+  attribute :parentComment
+  
+  collection :child, Comment, :parent
+  
+  reference :parent, Comment
+  reference :author, User
+  reference :workitem, WorkItem
+
+  class << self; attr_accessor :rules end
+  @rules = {
+    'title'			=> '//comment/field[@id="title"]',
+	'author'		=> '//comment/field[@id="author"]',
+	'text'			=> '//comment/field[@id="text"]',
+	'created'		=> '//comment/field[@id="created"]',
+	'parentComment'	=> '//comment/field[@id="parentComment"]'
+  }
+
+  # Retrieve a specific comment data
+  def retrieve
+    content = IO.readlines(url).join('')
+	doc = Nokogiri::XML(content)
+	self.class.rules.each_pair do |k,v|
+	  tmp = doc.xpath(v)
+
+	  case k
+		when 'author'
+		  self.send("#{k}=", User.find_by_name(tmp[0].content))
+		else
+		  self.send("#{k}=", tmp[0].content)  unless tmp[0].nil?		
+	  end
+	end
+	self.workitem = WorkItem.find_by_wid(File.dirname(self.url).split(/\//).last)
+	self.parent   = Comment.find_by_cid(self.parentComment) unless self.parentComment.nil?
+	Place.logger.info("retrieved comement for #{self.url}")
+    self.save
+  end
+  
+  # Find a comment by a "comment-id" (es: P-1#3)
+  def self.find_by_cid(cid)
+    comments = self.all.select do |c|
+	  chunks = c.url.split('/')
+	  wid = chunks[-2]
+	  comment_part = chunks[-1]
+	  comment_part =~ /comment-(\d+).xml/
+	  "#{wid}##{$1}" == cid
+	end
+	return comments.first  if comments.size > 0
+    return nil
+  end
+  
+  # Return a calculated cid for the comment
+  def cid
+    chunks = self.url.split('/')
+	wid = chunks[-2]
+	comment_part = chunks[-1]
+	comment_part =~ /comment-(\d+).xml/
+	"#{wid}#{$1}"
+  end
+  
+end
+
+end
+
+
+
+  

data/lib/place/link.rb

@@ -0,0 +1,20 @@
+module Place
+
+class Link < Ohm::Model
+  attribute :role
+  index :role
+  attribute :suspect
+  attribute :revision
+  
+  reference :from, WorkItem
+  reference :to, WorkItem
+  
+  # added only for performance needs
+  attribute :from_wid
+  index :from_wid
+  attribute :to_wid
+  index :to_wid
+end
+
+end
+

data/lib/place/participation.rb

@@ -0,0 +1,12 @@
+module Place
+
+
+class Participation < Ohm::Model
+  set :roles
+
+  reference :user, User
+  reference :project, Project
+end
+
+
+end

data/lib/place/project.rb

@@ -0,0 +1,159 @@
+module Place
+
+# Each project has a (name, url) from which (prefix, description) are derived
+class Project < Ohm::Model
+  attribute :name
+  attribute :description
+  attribute :prefix
+  attribute :url
+
+  index :name
+  index :url
+  index :prefix
+  
+  set :parent_roles
+  
+  collection :participations, Participation, :project
+  collection :workitems, WorkItem, :project
+  collection :timepoints, TimePoint, :project
+  
+  class << self; attr_accessor :rules end
+  @rules = {
+    'name'			=> '//project/field[@id="name"]',
+	'description'	=> '//project/field[@id="description"]',
+	'prefix'		=> '//project/field[@id="trackerPrefix"]'
+  }
+  
+  # Collect all projects (url) under a given repository url
+  def self.collect_all(base_url)
+    projects_path = base_url + '/**/.polarion'
+    Dir.glob(projects_path).each do |filename|
+	  next  if filename == base_url + '/.polarion'
+      Project.create(:url => filename)
+	  Place.logger.info("created project with url #{filename}")
+	end	
+  end
+
+  # Retrieve a specific project (based on url only)
+  def retrieve
+    start_time = Time.now.to_i
+
+    Dir.glob("#{url}/polarion-project.xml").each do |filename|
+	  content = IO.readlines(filename).join('')
+	  doc = Nokogiri::XML(content)
+	  
+	  self.class.rules.each_pair do |k,v|
+	    tmp = doc.xpath(v)
+		self.send("#{k}=", tmp[0].content)  unless tmp[0].nil?		
+	  end
+	end
+	self.save
+	Place.logger.info("saved project with name #{self.name}")
+	
+	retrieve_parent_roles
+	
+	TimePoint.collect_all(url)
+    timepoints.all.each{|tp| tp.retrieve}  if timepoints.size > 0
+	
+	WorkItem.collect_all(url)
+    workitems.all.each{|wi| wi.retrieve}  if workitems.size > 0
+
+	retrieve_participations
+
+	users.each do |u|
+	  # ugly way to prevent multiple (global) data retrieve :(
+	  u.retrieve  if u.full_name.nil?
+	  u.retrieve_watches
+	end
+	
+	self.save
+  end
+  
+  # Find a project by a given url (ending with +/.polarion+), +nil+ if not exists
+  def self.find_by_url(url)
+    projects = self.find(:url => url)
+    projects.nil? ? nil : projects[0]
+  end
+  
+  # Find a project by a given name, +nil+ if not exists
+  def self.find_by_name(name)
+    projects = self.find(:name => name)
+    projects.nil? ? nil : projects[0]
+  end
+  
+  # Find a project by a given perfix, +nil+ if not exists
+  def self.find_by_prefix(prefix)
+    projects = self.find(:prefix => prefix)
+    projects.nil? ? nil : projects[0]
+  end
+  
+  # Find all users involved in the project, eventually with a given role
+  def users(with_role=nil)
+    user_set = []
+	if participations.size > 0
+      participations.all.each do |pt|
+	    unless with_role.nil?
+  	      role = with_role.to_s
+		  roles = pt.roles.size > 0 ? pt.roles.to_a : []
+		  user_set << pt.user  if roles.include?(role)
+	    else
+  	      user_set << pt.user
+	    end
+	  end
+	end
+	user_set
+  end
+  
+  # Find all roles used in the project
+  def roles
+    tmp = {}
+    participations.all.each do |pt|
+	  if pt.roles.size > 0
+	    pt.roles.all.each{|r| tmp[r] = true}
+	  end
+	end
+	tmp.keys
+  end
+  
+private
+  
+  # Retrieve all participation of users in project, with its own roles
+  def retrieve_participations
+	Dir.glob("#{url}/security/user-roles.xml").each do |filename|
+	  content = IO.readlines(filename).join
+      doc = Nokogiri::XML(content)
+	  doc.xpath('//user-roles/user').each do |udata|
+	    u = User.find_by_name(udata['name'])
+		unless u.nil?
+		  p = Participation.create(:project => self, :user => u)
+		  udata.xpath('role').map{|i| i['name']}.each{|r| p.roles << r}
+		  p.save
+		  Place.logger.info("saved participation: #{u.name}, #{self.name}")
+		end
+	  end
+	end
+  end
+  
+  # Retrieve parent roles' id for the project
+  def retrieve_parent_roles
+    local_path  = "#{url}/tracker/fields/workitem-link-role-enum.xml"
+    _retrieve_parent_roles(local_path)
+	
+	# if they are not locally, find out globally
+	global_path = "#{Place.conf['base']}/.polarion/tracker/fields/workitem-link-role-enum.xml"
+	_retrieve_parent_roles(global_path)  if parent_roles.empty?
+  end
+    
+  def _retrieve_parent_roles(path)
+    Dir.glob(path).each do |filename|
+	  content = IO.readlines(filename).join
+	  doc = Nokogiri::XML(content)
+	  doc.xpath('//enumeration/option[@parent="true"]').each do |data|
+	    self.parent_roles << data.attributes['id'].to_s
+	  end
+	end
+  end
+  
+end
+
+end