confluencer 0.2.7 → 0.2.8

data/VERSION

@@ -1 +1 @@
-0.2.7
+0.2.8

data/confluencer.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{confluencer}
-  s.version = "0.2.7"
+  s.version = "0.2.8"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Gabor Ratky"]
-  s.date = %q{2010-05-07}
+  s.date = %q{2010-05-11}
   s.description = %q{ActiveRecord-like classes to access Confluence through XMLRPC.}
   s.email = %q{rgabo@rgabostyle.com}
   s.extra_rdoc_files = [
@@ -37,7 +37,10 @@ Gem::Specification.new do |s|
      "script/console",
      "script/console_init.rb",
      "spec/confluence.yaml.example",
+     "spec/confluence/bookmark_spec.rb",
+     "spec/confluence/client_spec.rb",
      "spec/confluence/page_spec.rb",
+     "spec/confluence/record_spec.rb",
      "spec/confluence/session_spec.rb",
      "spec/confluencer_spec.rb",
      "spec/spec.opts",
@@ -49,7 +52,10 @@ Gem::Specification.new do |s|
   s.rubygems_version = %q{1.3.6}
   s.summary = %q{Useful classes to manage Confluence.}
   s.test_files = [
-    "spec/confluence/page_spec.rb",
+    "spec/confluence/bookmark_spec.rb",
+     "spec/confluence/client_spec.rb",
+     "spec/confluence/page_spec.rb",
+     "spec/confluence/record_spec.rb",
      "spec/confluence/session_spec.rb",
      "spec/confluencer_spec.rb",
      "spec/spec_helper.rb"

data/lib/confluence/client.rb

@@ -1,67 +1,126 @@
 require 'xmlrpc/client'
 
-# Originally confluence4r, available at: http://confluence.atlassian.com/display/DISC/Confluence4r
-
-# 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:
-#
-# client = Confluence::Client.new(:url => "http://confluence.atlassian.com")
-# client.login("user", "password")
-# puts client.getSpaces()
-#
+# Module containing Confluence-related classes.
 module Confluence
+  # Originally confluence4r, available at: http://confluence.atlassian.com/display/DISC/Confluence4r
+
+  # 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)).
+  #
+  # Usage:
+  #
+  # client = Confluence::Client.new(:url => "http://confluence.atlassian.com")
+  # client.login("user", "password")
+  # p client.getSpaces
+  #
   class Client
     PREFIX = "confluence1"
+    XMLRPC_SUFFIX = "/rpc/xmlrpc"
     
-    attr_reader :username, :token
-     
-		def initialize(options = {})
-		  server_url = options[:url]
-			server_url += "/rpc/xmlrpc" unless server_url[-11..-1] == "/rpc/xmlrpc"
-			@server_url = server_url
-			
-			client = XMLRPC::Client.new_from_uri(server_url)
+    attr_reader :url, :username, :token
+
+    # Initializes a new client with the given arguments.
+    #
+    # ==== Parameters
+    # arguments<Hash>:: Described below.
+    #
+    # ==== Arguments
+    # :url    - The url of the Confluence instance. The trailing '/rpc/xmlrpc' path is optional.
+    # :token  - An existing session token to reuse.
+    #
+		def initialize(arguments = {})
+		  @url = arguments[:url]
+			@token = arguments[:token]
 			
-			@confluence = client.proxy(PREFIX)
-			@token = options[:token]
+      Log4r::MDC.put('token', @token || 'nil')
+			log.info "initialized client (:url => #{@url}, :token => #{@token || 'nil'})"
 		end
-		
+
+	  # Returns true, if the client has a session token.
+	  #
 		def has_token?
 		  !@token.nil?
 	  end
 	  
+	  # Logs in and returns the newly acquired session token.
+	  #
+	  # ==== Parameters
+	  # username<String>:: The username.
+	  # password<String>:: The password.
+	  #
 		def login(username, password)
-			@username = username
-			@password = password
+		  handle_fault do
+		    if @token = proxy.login(username, password)
+    			Log4r::MDC.put('token', @token)
+    			log.info "logged in as '#{username}' and acquired token."
 
-		  request do |confluence|
-		    @token = confluence.login(@username, @password)
+  		    @username = username
+    			@password = password
+        end  			
 	    end
+	    
+	    @token
 		end
 		
+		# Logs out and invalidates the session token.
+		#
 		def logout
-		  request do |confluence|
-		    confluence.logout(@token)
+		  handle_fault do
+	      @token = nil if @token and result = proxy.logout(@token)
+	      log.info "logged out"
+	      Log4r::MDC.put('token', 'nil')
+	      result
 	    end
 		end	
 
+    # Translates every call into XMLRPC calls.
+    #
 		def method_missing(method_name, *args)
-		  request do |confluence|
-		    confluence.send(method_name, *([@token] + args))
+		  handle_fault do
+		    if args.empty?
+  		    log.debug "#{method_name}"
+		    else
+		      log.debug "#{method_name}(#{args.join(', ')})"
+	      end
+ 		    result = proxy.send(method_name, *([@token] + args))
+ 		    log.debug(result.inspect)
+ 		    result
 	    end
 		end
 		
 		private
-		
-		def request(&block)
+
+    # Returns the Confluence::Client logger.
+		def log
+		  Log4r::Logger[Confluence::Client.to_s] || Log4r::Logger.root
+	  end
+	  
+		# Returns the Confluence XMLRPC endpoint url.
+	  #
+	  def xmlrpc_url
+	    unless @url[-11..-1] == XMLRPC_SUFFIX
+	      @url + XMLRPC_SUFFIX
+      else
+        @url
+      end
+    end
+    
+    # Returns the XMLRPC client proxy for the Confluence API v1.
+    #
+		def proxy
+		  @proxy ||= XMLRPC::Client.new_from_uri(xmlrpc_url).proxy(PREFIX)
+	  end
+	  
+	  # Yields and translates any XMLRPC::FaultExceptions raised by Confluence to Confluence::Errors.
+	  #
+		def handle_fault(&block)
 		  begin
-		    block.call(@confluence)
+		    block.call
 			rescue XMLRPC::FaultException => e
-        case message = e.faultString.rpartition(':').last
+			  log.warn message = e.faultString.rpartition(':').last
+			  
+        case message
 		    when /Transaction rolled back/
 		      raise Confluence::Error, "Could not save or update record."
 	      else

data/lib/confluence/record.rb

@@ -1,8 +1,16 @@
 module Confluence
   class Record
     class << self
+      def client
+        raise "Confluence client is unavailable. Did you forget to use Confluence::Session.new?" unless @@client
+        @@client
+      end
+
+      def client=(value)
+        @@client = value
+      end
+      
       def record_attr_accessor(*args)
-        
         attributes = {}
         
         # iterate through each argument
@@ -31,7 +39,12 @@ module Confluence
     attr_accessor :attributes
     
     def initialize(hash)
-      @attributes = Hash[*(hash.keys.map {|k| k.to_sym}).zip(hash.values).flatten]
+      @attributes = {}
+
+      # iterate through each key/value pair and set attribute keyed by symbol
+      hash.each_pair do |key, value|
+        self[key.to_sym] = value
+      end
     end
         
     def [](attr)
@@ -47,27 +60,17 @@ module Confluence
     end
     
     def labels
-      client.getLabelsById(record_id).collect {|label| label["name"]}
+      @labels ||= client.getLabelsById(record_id).collect {|label| label["name"]}
     end
     
     def labels=(value)
-      existing_labels = labels
-      removed_labels = existing_labels - value
-      added_labels = value - existing_labels
+      removed_labels = labels - value
+      added_labels = value - labels
       
       client.removeLabelByName(removed_labels.join(" "), record_id) unless removed_labels.empty?
       client.addLabelByName(added_labels.join(" "), record_id) unless added_labels.empty?
-    end
-    
-    @@client = nil
-
-    def self.client
-      raise "Confluence client is unavailable. Did you forget to use Confluence::Session.new?" unless @@client
-      @@client
-    end
-    
-    def self.client=(client)
-      @@client = client
+      
+      @labels = value
     end
     
     def client

data/lib/confluence/session.rb

@@ -1,11 +1,22 @@
 module Confluence
+  # Wraps a Confluence::Client and manages the lifetime of a session.
+  #
   class Session
     attr_reader :client
     
-    def token
-      client.token if client
-    end
-    
+    # Initializes a new session with the given arguments and sets it for other classes like Confluence::Page.
+    #
+    # If a block is given to initialize, initialize yields with the Confluence::Client and automatically logs out of the session afterwards. 
+    # Otherwise Session#destroy should be called after finished.
+    #
+    # ==== Parameters
+    # arguments<Hash>:: Described below.
+    #
+    # ==== Arguments
+    # :url      - The url of the Confluence instance.
+    # :username - The username.
+    # :password - The password.
+    #
     def initialize(arguments = {})
       raise ArgumentError, "Required argument 'url' is missing." unless arguments.key? :url
       
@@ -19,30 +30,33 @@ module Confluence
       end
 
       # set client for records
-      Confluence::Record::client = @client
+      Confluence::Record.client = @client
 
+      # yield if block was given and destroy afterwards
       if block_given?
-        begin
-          yield @client
-        rescue RuntimeError => e
-          # strip non-message part of java exception message
-          raise e.message.split(":").last.strip
-        end
+        yield @client
 
         self.destroy
       end
     end
     
+    # Returns the current session token.
+    #
+    def token
+      client.token if client
+    end
+    
+    # Destroys the session by logging out and resets other classes like Confluence::Page.
+    #
     def destroy
       # invalidate the token
       client.logout
       
-      # client and token is not valid anymore
+      # client is not valid anymore
       @client = nil
-      @token = nil
       
       # reset client for records
-      Confluence::Record::client = nil
+      Confluence::Record.client = nil
     end
   end
 end

data/lib/confluencer.rb

@@ -1,6 +1,9 @@
 # ensure that lib is in the load path
 $:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
+require 'rubygems'
+require 'log4r'
+
 require 'confluence/error'
 
 require 'confluence/client'
@@ -10,3 +13,7 @@ require 'confluence/record'
 require 'confluence/page'
 require 'confluence/bookmark'
 require 'confluence/blog_entry'
+
+module Confluencer
+  VERSION = "0.2.7"
+end

data/spec/confluence.yaml.example

@@ -4,4 +4,30 @@
     :username:      roger
     :password:      jessica
     :space:         confluencer
-    :page_title:    Confluencer RSpec Test Page
+    :page_title:    Confluencer RSpec Test Page
+    
+# Log4r configuration
+log4r_config:
+    pre_config:
+        global:
+            level: DEBUG
+        root:
+            level: DEBUG
+
+    # loggers
+    loggers:
+      - name        : Confluence::Client
+        level       : DEBUG
+        additive    : 'false'
+        trace       : 'false'
+        outputters:
+          - stdout
+
+    # outputters
+    outputters:
+      - type     : StdoutOutputter
+        name     : stdout 
+        level    : DEBUG
+        formatter:
+          type        : PatternFormatter
+          pattern     : '%d %C (%X{token}) [%l]: %m'

data/spec/confluence/bookmark_spec.rb

@@ -0,0 +1,4 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'spec_helper'))
+
+describe Confluence::Bookmark do
+end

data/spec/confluence/client_spec.rb

@@ -0,0 +1,74 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'spec_helper'))
+
+describe Confluence::Client do
+  include ConfigurationHelperMethods
+  
+  def new_client_from_config
+    Confluence::Client.new(config)
+  end
+  
+  def logged_in_client
+    client = new_client_from_config
+    client.login(config[:username], config[:password])
+    client.has_token?.should be_true
+    client
+  end
+  
+  it "can initialize a client with a url" do
+    client = Confluence::Client.new :url => "http://confluence.atlassian.com"
+    
+    client.should_not be_nil
+    client.url.should_not be_nil
+    client.url.should == "http://confluence.atlassian.com"
+  end
+  
+  it "can initialize a client with an existing token" do
+    client = Confluence::Client.new :url => "http://confluence.atlassian.com", :token => "abcdef"
+    client.token.should_not be_nil
+    client.token.should == "abcdef"
+  end
+  
+  it "can return whether a token is already available" do
+    client = Confluence::Client.new :url => "http://confluence.atlassian.com"
+    client.has_token?.should be_false
+    
+    client = Confluence::Client.new :url => "http://confluence.atlassian.com", :token => "abcdef"
+    client.has_token?.should be_true
+  end
+  
+  it "can log in and acquire a session token" do
+    client = new_client_from_config
+    client.has_token?.should be_false
+    
+    token = client.login(config[:username], config[:password])
+    token.should_not be_nil
+    
+    client.has_token?.should be_true
+    client.token.should == token
+  end
+  
+  it "raises an error if it cannot login" do
+   client = new_client_from_config
+   
+   lambda { client.login(config[:username], "bogus") }.should raise_exception(Confluence::Error, /incorrect password/)
+   client.has_token?.should be_false
+   
+   lambda { client.login("bogus", "bogus") }.should raise_exception(Confluence::Error, /no user could be found/)
+   client.has_token?.should be_false
+  end
+  
+  it "can logout and invalidate a session token" do
+    client = logged_in_client
+    
+    client.logout.should be_true
+    client.has_token?.should be_false
+  end
+  
+  it "can make XMLRPC calls" do
+    client = logged_in_client
+    
+    server_info = client.getServerInfo
+    server_info.should_not be_nil
+    server_info["baseUrl"].should == client.url
+  end
+end

data/spec/confluence/page_spec.rb

@@ -21,9 +21,9 @@ describe Confluence::Page do
     new_session do
       begin
         # check whether we need to remove the test page
-        test_page = Confluence::Page.find_by_title config[:space], config[:page_title]
+          test_page = Confluence::Page.find_by_title config[:space], config[:page_title]
         test_page.remove if test_page
-      rescue RuntimeError
+      rescue Confluence::Error
       end
     end    
   end
@@ -31,7 +31,7 @@ describe Confluence::Page do
   it "should add a new page in Confluence" do
     page = nil
     
-    new_session do
+    new_session do |client|
       # initialize test page
       page = create_test_page
       

data/spec/confluence/record_spec.rb

@@ -0,0 +1,9 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'spec_helper'))
+
+describe Confluence::Record do
+  it "should initialize new record from Confluence hash" do
+    record = Confluence::Record.new :foo => 'bar'
+    
+    record[:foo].should == 'bar'
+  end
+end

data/spec/spec_helper.rb

@@ -6,7 +6,12 @@ require 'spec'
 require 'spec/autorun'
 require 'yaml'
 
+require 'log4r/yamlconfigurator'
+
 Spec::Runner.configure do |config|
+  config.before :suite do
+    Log4r::YamlConfigurator.load_yaml_file(File.join(File.dirname(__FILE__), 'confluence.yaml'))
+  end
 end
 
 module ConfigurationHelperMethods
@@ -22,7 +27,7 @@ module SessionHelperMethods
   def new_session
     if block_given?
       # initialize session and yield
-      Confluence::Session.new config { yield }
+      Confluence::Session.new(config) {|client| yield client }
     else
       # initialize session and return
       Confluence::Session.new config

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 2
-  - 7
-  version: 0.2.7
+  - 8
+  version: 0.2.8
 platform: ruby
 authors: 
 - Gabor Ratky
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-07 00:00:00 +02:00
+date: 2010-05-11 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -61,7 +61,10 @@ files:
 - script/console
 - script/console_init.rb
 - spec/confluence.yaml.example
+- spec/confluence/bookmark_spec.rb
+- spec/confluence/client_spec.rb
 - spec/confluence/page_spec.rb
+- spec/confluence/record_spec.rb
 - spec/confluence/session_spec.rb
 - spec/confluencer_spec.rb
 - spec/spec.opts
@@ -97,7 +100,10 @@ signing_key:
 specification_version: 3
 summary: Useful classes to manage Confluence.
 test_files: 
+- spec/confluence/bookmark_spec.rb
+- spec/confluence/client_spec.rb
 - spec/confluence/page_spec.rb
+- spec/confluence/record_spec.rb
 - spec/confluence/session_spec.rb
 - spec/confluencer_spec.rb
 - spec/spec_helper.rb