confluence4r 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 41dcb8b373b04bf307d72faacb8344bd9a8beea4
+  data.tar.gz: 723450b5298bd65a9190f390baa09fd4801576ca
+SHA512:
+  metadata.gz: 5fd675efc44a93f1f50a33d297c560cc9b71421d5dd35f024626b30d59ad4d1a6699b475e069853e0c6a25477ee3a9faed289e0eb41247e15072bf0b9e6bf7c6
+  data.tar.gz: 403f58e7d0e9ec5eb4c4120325429088cd1aa3559859380b5b9e9250c19a2ec2d7826c6ac147831e3725342625fd2bd62504faa73784017376940868e560a448

data/lib/confluence/confluence_connector.rb

@@ -0,0 +1,64 @@
+require 'yaml'
+
+require 'confluence/confluence_rpc'
+
+class Confluence::Connector
+  
+  attr_accessor :username, :password, :default_service, :url, 
+                :admin_proxy_username, :admin_proxy_password
+
+  def initialize(options = {})
+    load_confluence_config
+    @url ||= options[:url]
+    @username = options[:username] || @username
+    @password = options[:password] || @password
+    @default_service = options[:service] || 'confluence1'
+  end
+  
+  def connect(service = nil)
+    unless url and ((admin_proxy_username and admin_proxy_password) or (username and password)) and service || default_service
+      raise "Cannot get Confluence::RPC instance because the confluence url, username, password, or service have not been set"
+    end
+    
+    rpc = Confluence::RPC.new(url, service || default_service)
+    rpc.login(username, password)
+
+    return rpc
+  end
+  
+  def load_confluence_config
+    conf = YAML.load_file("#{RAILS_ROOT}/config/confluence.yml")[RAILS_ENV]
+    @url = conf['url'] || conf[:url]
+    @default_service = conf['service'] || conf[:service]
+    @admin_proxy_username = conf['admin_proxy_username'] || conf[:admin_proxy_username]
+    @admin_proxy_password = conf['admin_proxy_password'] || conf[:admin_proxy_password]
+    # take these params manually if that's what is sent
+    @username = conf['username'] || conf[:username] || @admin_proxy_username
+    @password = conf['password'] || conf[:password] || @admin_proxy_password
+  end
+  
+  def self.default_confluence_url
+    conf = YAML.load_file("#{RAILS_ROOT}/config/confluence.yml")[RAILS_ENV]
+    conf['url'] || conf[:url]
+  end
+  
+  # The given block will be executed using another account, as set in the confluence.yml file under admin_proxy_username
+  # and admin_proxy_password. This is useful when you want to execute some function that requires admin privileges. You
+  # will of course have to set up a corresponding account on your Confluence server with administrative rights.
+  def self.through_admin_proxy
+    super_connector = Confluence::Connector.new
+    
+    raise "Cannot execute through_admin_proxy because the admin_proxy_username has not been set." unless super_connector.admin_proxy_username
+    raise "Cannot execute through_admin_proxy because the admin_proxy_password has not been set." unless super_connector.admin_proxy_password
+    
+    super_connector.username = super_connector.admin_proxy_username
+    super_connector.password = super_connector.admin_proxy_password
+    
+    normal_connector = Confluence::RemoteDataObject.connector
+    Confluence::RemoteDataObject.connector = super_connector
+    
+    yield
+    
+    Confluence::RemoteDataObject.connector = normal_connector
+  end
+end

data/lib/confluence/confluence_remote_data_object.rb

@@ -0,0 +1,187 @@
+require 'active_support'
+require 'confluence/confluence_connector'
+
+# Abstract object representing some piece of data in Confluence.
+# This must be overridden by a child class that defines values
+# for the class attributes save_method and get_method and/or
+# implements its own get and save methods.
+class Confluence::RemoteDataObject
+#  include Reloadable
+  
+  class_inheritable_accessor :attr_conversions, :readonly_attrs
+  class_inheritable_accessor :save_method, :get_method, :destroy_method
+  
+  attr_accessor :attributes
+  
+  attr_accessor :confluence, :encore
+  
+  @@connector = nil
+  
+  def self.connector=(connector)
+    @@connector = connector
+  end
+  
+  def self.connector
+    @@connector
+  end
+  
+  def self.confluence
+    raise "Cannot establish confluence connection because the connector has not been set." unless @@connector
+    @@connector.connect
+  end
+  
+  def confluence
+    raise "Cannot establish confluence connection because the connector has not been set." unless @@connector
+    @@connector.connect
+  end
+  
+  # TODO: encore-specific code like this probably shouldn't be here...
+  def self.encore
+    raise "Cannot establish confluence connection because the connector has not been set." unless @@connector
+  	@@connector.connect("encore")
+  end
+  
+  def encore
+    raise "Cannot establish confluence connection because the connector has not been set." unless @@connector
+    @@connector.connect("encore")
+  end
+  
+  def initialize(data_object = nil)
+    self.attributes = {}
+    load_from_object(data_object) unless data_object.nil?
+  end
+  
+  def load_from_object(data_object)
+    data_object.each do |attr, value|
+      if self.class.attr_conversions.has_key? attr.to_sym
+        value = self.send("as_#{attr_conversions[attr.to_sym]}", value)
+      end
+      self.send("#{attr}=", value)
+    end
+  end
+  
+  def save
+    before_save if respond_to? :before_save
+    
+    data = {} unless data
+    
+    self.attributes.each do |attr,value|
+      data[attr.to_s] = value.to_s unless self.readonly_attrs.include? attr
+    end
+    
+    raise NotImplementedError.new("Can't call #{self}.save because no @@save_method is defined for this class") unless self.save_method
+    
+    self.confluence.send(self.class.send(:save_method), data)
+    
+    # we need to reload because the version number has probably changed, we want the new ID, etc.
+    reload
+    
+    after_save if respond_to? :after_save
+  end
+  
+  def reload
+    before_reload if respond_to? :before_reload
+    
+    if self.id
+      self.load_from_object(self.class.send(:get, self.id))
+    else
+      # We don't have an ID, so try to use alternate method for reloading. (This is for newly created records that may not yet have an id assigned)
+      raise NotImplementedError, "Can't reload this #{self.class} because it does not have an id and does not implement the reload_newly_created! method." unless self.respond_to? :reload_newly_created!
+      self.reload_newly_created!
+    end
+    
+    after_reload if respond_to? :after_reload
+  end
+  
+  def destroy
+    before_destroy if respond_to? :before_destroy
+    
+    raise NotImplementedError.new("Can't call #{self}.destroy because no @@destroy_method is defined for this class") unless self.destroy_method
+    eval "confluence.#{self.destroy_method}(self.id.to_s)"
+    
+    after_destroy if respond_to? :after_destroy
+  end
+  
+  def [](attr)
+    self.attributes[attr]
+  end
+  
+  def []=(attr, value)
+    self.attributes[attr] = value
+  end
+  
+  def id
+    self[:id]
+  end
+  
+  def method_missing(name, *args)
+    if name.to_s =~ /^(.*?)=$/
+      self[$1.intern] = args[0]
+    elsif name.to_s =~ /^[\w_]+$/
+      self[name]
+    else
+      raise NoMethodError, name.to_s
+    end
+  end
+  
+  def ==(obj)
+    if obj.kind_of? self.class
+      self.attributes == obj.attributes
+    else
+      super
+    end
+  end
+  
+  ### class methods #########################################################
+  
+  def self.find(id)
+    r = get(id)
+    self.new(r)
+  end
+  
+  ### type conversions ######################################################
+  
+  # TODO: put these in a module?
+  def as_int(val)
+    val.to_i
+  end
+  
+  def as_string(val)
+    val.to_s
+  end
+  
+  def as_boolean(val)
+    val == "true"
+  end
+  
+  def as_datetime(val)
+    if val.is_a?(String) 
+      # for older versions of Confluence (pre 2.7?)
+      val =~ /\w{3} (\w{3}) (\d{2}) (\d{2}):(\d{2}):(\d{2}) (\w{3}) (\d{4})/
+      month = $1
+      day = $2
+      hour = $3
+      minute = $4
+      second = $5
+      tz = $6
+      year = $7
+      Time.local(year, month, day, hour, minute, second)
+    else
+      Time.local(val.year, val.month, val.day, val.hour, val.min, val.sec)
+    end
+  end
+  
+  ###########################################################################
+  
+  protected
+    # Returns the raw XML-RPC anonymous object with the data corresponding to 
+    # the given id. This depends on the get_method class attribute, which must
+    # be defined for this method to work.
+    def self.get(id)
+      raise NotImplementedError.new("Can't call #{self}.get(#{id}) because no get_method is defined for this class") unless self.get_method
+      raise ArgumentError.new("You must specify a #{self} id!") unless id
+      confluence.log.debug("get_method for #{self} is #{self.get_method}")
+      obj = confluence.send(self.send(:get_method), id.to_s)
+      return obj
+    end
+end

data/lib/confluence/confluence_rpc.rb

@@ -0,0 +1,83 @@
+require 'xmlrpc/client'
+require 'logger'
+
+# A useful helper for running Confluence XML-RPC from Ruby. Takes care of
+# adding the token to each method call (so you can call server.getSpaces()
+# instead of server.getSpaces(token)). Also takes care of re-logging in
+# if your login times out.
+#
+# Usage:
+#
+# server = Confluence::RPC.new("http://confluence.atlassian.com")
+# server.login("user", "password")
+# puts server.getSpaces()
+#
+module Confluence
+
+  class RPC
+    attr_reader :log
+    
+    def initialize(server_url, proxy = "confluence1")
+      server_url += "/rpc/xmlrpc" unless server_url[-11..-1] == "/rpc/xmlrpc"
+      @server_url = server_url
+      server = XMLRPC::Client.new2(server_url)
+      @conf = server.proxy(proxy)
+      @token = "12345"
+      
+      @log = Logger.new "#{RAILS_ROOT}/log/confluence4r.log"
+    end
+    
+    def login(username, password)
+      log.info "Logging in as '#{username}'."
+      @user = username
+      @pass = password
+      do_login()
+    end
+    
+    def method_missing(method_name, *args)
+      log.info "Calling #{method_name}(#{args.inspect})."
+      begin
+        @conf.send(method_name, *([@token] + args))
+      rescue XMLRPC::FaultException => e
+        log.error "#{e}: #{e.message}"
+        if (e.faultString.include?("InvalidSessionException"))
+          do_login
+          retry
+        else
+          raise RemoteException, e.respond_to?(:message) ? e.message : e
+        end
+      rescue
+        log.error "#{$!}"
+        raise $!
+      end
+    end
+    
+    private
+    
+    def do_login()
+      begin
+        @token = @conf.login(@user, @pass)
+      rescue XMLRPC::FaultException => e
+        log.error "#{e}: #{e.faultString}"
+        raise RemoteAuthenticationException, e
+      end
+    end
+  end
+  
+  
+  class RemoteException < Exception
+    def initialize(msg = nil, type = nil)
+      if msg.kind_of? XMLRPC::FaultException
+        msg.faultString =~ /^.*?:\s(.*?):\s(.*)/
+        msg = $2
+        type = $1
+      end
+    
+      super(msg)
+      @type = type
+    end
+  end
+  
+  class RemoteAuthenticationException < RemoteException
+  end
+end

data/lib/confluence/metadata.rb

@@ -0,0 +1,117 @@
+# Allows for reading and writing a {metadata-list} macro in a page's content.
+# 
+# For example, if your wiki content is:
+# 
+#   Hello, World!
+#   {metadata-list}
+#   || Foo   | Bar |
+#   || Fruit | Orange |
+#   {metadata-list}
+# 
+# You may do this (assuming that you have the above text stored in a variable
+# called 'wiki_content'):
+# 
+#   m = Confluence::Metadata.new(wiki_content)
+#   puts m['Foo']    # outputs "Bar"
+#   puts m['Fruit']  # outputs "Orange"
+#   
+#   m['Fruit'] = "Banana"
+#   puts m['Fruit']  # outputs "Banana"
+#   m['Hello'] = "Goodbye"
+#   
+# ... and your wiki_content now holds:
+# 
+#   Hello, World!
+#   {metadata-list}
+#   || Foo   | Bar |
+#   || Fruit | Banana |
+#   || Hello | Goodbye |
+#   {metadata-list}
+#
+class Confluence::Metadata
+  include Enumerable
+
+  def initialize(page)
+    raise ArgumentError.new("Argument passed to Confluence::Metadata must be a Confluence::Page") unless page.kind_of? Confluence::Page
+    @page = page
+  end
+  
+  def [](metadata_key)
+    extract_metadata_from_content[metadata_key]
+  end
+  
+  def []=(metadata_key, value)
+    metadata = extract_metadata_from_content
+    metadata[metadata_key] = value
+    replace_metadata_in_content(metadata)
+    value
+  end
+  
+  def each
+    metadata = extract_metadata_from_content
+    metadata.each{|k,v| yield k,v}
+  end
+  
+  def include?(key)
+    not self.find{|k,v| k}.nil?
+  end
+  alias_method :has_key?, :include?
+  
+  def empty?
+    extract_metadata_from_content.empty?
+  end
+  
+  # Merges a hash (or some other Hash-like, Enumerable object) into
+  # this metadata. That is, key-value pairs from the given object will be added
+  # as metadata to this Confluence::Metadata's page, overriding any existing duplicate keys.
+  def merge!(data)
+    data.each do |k,v|
+      self[k] = v
+    end
+  end
+  
+  private
+    def extract_metadata_from_content
+      return {} if @page.content.nil?
+    
+      in_body = false
+      metadata = {}
+      @page.content.each do |line|
+        #TODO: handle other kinds of metadata macros
+        in_body = !in_body if line =~ /\{metadata-list\}/
+        
+        if in_body        
+          metadata[$1] = $2 if line =~ /\|\|\s*(.*?)\s*\|\s*(.*?)\s*\|/
+        end
+      end
+      
+      return metadata
+    end
+    
+    def replace_metadata_in_content(metadata)
+      #TODO: handle cases where there are multiple {metadata-list} macros in a page
+      #TODO: handle other kinds of metadata macros
+      
+      macro_name = "{metadata-list}"
+      
+      @page.content = "" if @page.content.nil?
+      
+      @page.content += "\n#{macro_name}\n\n#{macro_name}" unless @page.content.include? macro_name
+      
+      metadata_start = @page.content.index(macro_name) + macro_name.size
+      metadata_end = @page.content.index(macro_name, metadata_start) - 1
+      
+      longest_key = 0
+      metadata.each do |key, val|
+        longest_key = key.size if key.size > longest_key
+      end
+      
+      metadata_body = ""
+      metadata.each do |key, val|
+        padding = " " * (longest_key - key.size)
+        metadata_body += "|| #{key}#{padding} | #{val} |\n"
+      end
+      
+      @page.content[metadata_start..metadata_end] = "\n"+metadata_body
+    end
+end

data/lib/confluence/page.rb

@@ -0,0 +1,139 @@
+require 'confluence/confluence_remote_data_object'
+
+# Exposes a vaguely ActiveRecord-like interface for dealing with Confluence::Pages
+# in Confluence.
+class Confluence::Page < Confluence::RemoteDataObject
+
+  self.save_method = :storePage
+  self.get_method = :getPage
+  self.destroy_method = :removePage
+
+  self.attr_conversions = {
+      :id => :int,
+      :version => :int,
+      :parentId => :int,
+      :current => :boolean,
+      :homePage => :boolean,
+      :created => :datetime,
+      :modified => :datetime
+    }
+    
+  self.readonly_attrs = [:current, :created, :modified, :contentStatus]
+
+  DEFAULT_SPACE = "encore"
+  
+  def initialize(data_object = nil)
+    super
+    #self.creator = self.confluence_user unless self.include? :creator
+  end
+  
+  def name=(new_name)
+    self.title = new_name
+  end
+  
+  def name
+    self.title
+  end
+  
+  def content=(new_content)
+    # make sure metadata doesn't get overwritten
+    old_metadata = self.metadata.entries if self.content
+    super
+    self.metadata.merge! old_metadata if old_metadata
+  end
+  
+  def load_from_object(data_object)
+    super
+    self.modifier = self.confluence_username unless self.attributes.include? :modifier
+  end
+  
+  def metadata
+    Confluence::Metadata.new(self)
+  end
+  
+  def parent
+    self.class.find(self.parentId)
+  end
+  
+  def to_s
+    self.title
+  end
+  
+  def edit_group=(group)
+    encore.setPageEditGroup(self.title, group)
+  end
+  
+  def edit_group
+  	perm = get_permissions
+  	return nil if perm.nil? or perm.empty?
+  	perm.each do |p|
+  		return p['lockedBy'] if p['lockType'] == 'Edit'
+  	end
+  	return nil
+  end
+  
+  def view_group=(group)
+    encore.setPageViewGroup(self.title, group)
+  end
+  
+  def view_group
+  	perm = get_permissions
+  	return nil if perm.nil? or perm.empty?
+  	perm.each do |p|
+  		return p['lockedBy'] if p['lockType'] == 'View'
+  	end
+  	return nil
+  end
+  
+  def get_permissions
+  	confluence.getPagePermissions(self.id.to_s)
+  end
+  
+  ### callbacks ###############################################################
+  
+  def before_save
+    raise "Cannot save this page because it has no title and/or space." unless self.title and self.space
+  end
+  
+  #############################################################################
+  
+  ### class methods ###########################################################
+    
+  def self.find_by_name(name, space = DEFAULT_SPACE)
+    find_by_title(name, space)    
+  end
+  
+  def self.find_by_title(title, space = DEFAULT_SPACE)
+    begin
+      r = confluence.getPage(space, title)
+    rescue Confluence::RemoteException => e
+      # FIXME: dangerous to be checking based on error string like this...
+      if e.message =~ /does not exist/
+        return nil
+      else
+        raise e
+      end
+    end
+    self.new(r)
+  end
+  
+  
+  #############################################################################
+  
+  protected
+    def self.metadata_accessor(accessor, metadata_key)
+      f = <<-END
+        def #{accessor.to_s}
+          self.metadata['#{metadata_key}']
+        end
+        def #{accessor.to_s}=(val)
+          self.metadata['#{metadata_key}'] = val.gsub("\n", " ")
+        end
+      END
+      module_eval f
+    end
+    
+    def reload_newly_created!
+      self.load_from_object(confluence.getPage(self.space, self.title))
+    end
+end

data/lib/confluence/user.rb

@@ -0,0 +1,112 @@
+require 'confluence/confluence_remote_data_object'
+
+class Confluence::User < Confluence::RemoteDataObject
+
+  self.save_method = :editUser
+  # TODO: implement :create_method ('addUser')
+  self.get_method = :getUser
+  self.destroy_method = :removeUser
+    
+  self.readonly_attrs = ['username', 'name']
+  self.attr_conversions = {}
+  
+  @groups
+  
+  def id
+    self.username
+  end
+  
+  def id=(new_id)
+    self.username = new_id
+  end
+  
+  def username
+    self.name
+  end
+  
+  def username=(new_username)
+    self.username=(new_username)
+  end
+  
+  def groups
+    # groups are cached for the lifetime of the user object or until a group-modifying method is called
+    # FIXME: This is probably a bad idea, since the user's groups may be changed outside of the user object
+    #         ... currently it's not a serious problem, since this is unlikely to happen within the object's
+    #         short lifetime, but it may be problematic if start storing the user object in a cache or in the
+    #         session.
+    @groups ||= confluence.getUserGroups(username)
+  end
+  
+  def in_group?(group)
+    groups.include? group
+  end
+  
+  def add_to_group(group)
+    @groups = nil # reset cached group list
+    confluence.addUserToGroup(username, group)
+  end
+  
+  def remove_from_group(group)
+    @groups = nil # reset cached group list
+    confluence.removeUserFromGroup(username, group)
+  end
+  
+  def has_permission?(permtype, page)
+    if permtype == :edit
+      group_or_name = page.edit_group
+    else
+      group_or_name = page.view_group
+    end
+        
+    return true if group_or_name.nil?
+    return true if group_or_name == username
+    return in_group?(group_or_name)
+  end
+ 
+    def add_profile_picture(filename, mime_type, picture_data)
+        confluence.addProfilePicture(self.username, filename, mime_type, picture_data)
+    end
+          
+  def to_s
+    self.username
+  end
+  
+  def to_wiki
+    "[~#{self.username}]"
+  end
+  
+  ### class methods #########################################################
+    
+  def self.find_by_username(username)
+    find(username)
+  end
+  
+  # DEPRECATED: this method is confusing since it could be taken as meaning "find by first/last name"
+  def self.find_by_name(username)
+    find_by_username(username)
+  end
+  
+  def self.find_by_email(email)
+    usernames = confluence.getActiveUsers(true)
+    usernames.each do |username|
+      user = find_by_username(username)
+      return user if user.email == email
+    end
+    
+    return nil
+  end
+  
+  def self.find_all
+    # FIXME: this is really slow... we should probably just look in the confluence database instead
+    usernames = find_all_usernames
+    usernames.collect{|u| find_by_username(u)}
+  end
+  
+  def self.find_all_usernames
+    confluence.getActiveUsers(true)
+  end
+  
+  class NoSuchUser < Exception
+  end
+  
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: confluence4r
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Atlassian and Alagu
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-06-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Atlassian Confluence XML::RPC client
+email: alagu@goyaka.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/confluence/confluence_connector.rb
+- lib/confluence/confluence_remote_data_object.rb
+- lib/confluence/confluence_rpc.rb
+- lib/confluence/metadata.rb
+- lib/confluence/page.rb
+- lib/confluence/user.rb
+homepage: http://confluence.atlassian.com/display/DISC/Confluence4r
+licenses:
+- unknown
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements:
+- none
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Atlassian Confluence XML::RPC client
+test_files: []