ecircle_soap_client 0.0.5

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rvmrc

@@ -0,0 +1 @@
+rvm use --create ree-1.8.7-2011.03@ecirclegemset

data/Gemfile

@@ -0,0 +1,20 @@
+# -*- mode: ruby -*-
+source "http://rubygems.org"
+
+gem 'rake', "= 0.8.7"
+gem 'savon'
+gem 'nokogiri'
+gem 'multipart-post', :git => 'git://github.com/gorenje/multipart-post.git'
+gem 'uuidtools'
+
+group :development do
+  gem 'pry'
+  gem 'pry-doc'
+  gem 'gist'
+  gem "thoughtbot-shoulda", ">= 0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.6.4"
+  gem "rcov", ">= 0"
+  gem 'rr'
+  gem "cheat"
+end

data/README.md

@@ -0,0 +1,89 @@
+eCircle SOAP Client
+===================
+
+Warning
+-------
+Experimental code and not yet complete. Lots of testing are missing and functionality is limited.
+Simple things like creating and deleting users and groups is possible, but message creation and
+sending are not yet supported.
+
+Description
+-----------
+
+Based on [Savon](http://savonrb.com/) and [Nokogiri](http://nokogiri.org/) and provides a simple interface for accessing the eCircle [WSDL synchronous API](http://www.soapclient.com/soapclient?template=%2Fclientform.html&fn=soapform&SoapTemplate=%2FSoapResult.html&SoapWSDL=http%3A%2F%2Fwebservices.ecircle-ag.com%2Fsoap%2Fecm.wsdl&_ArraySize=2).
+
+Intention is to provide a ActiveRecord/ActiveModel-like interface to the individual entities provided by the SOAP API. It's far from complete and you can only do a few selected things with this gem.
+
+Installation
+------------
+
+Currently only via bundle with:
+
+```
+gem 'ecircle_soap_client', :git => 'git://github.com/gorenje/ecircle_soap_client.git'
+```
+
+Usage
+-----
+
+Configration:
+
+```
+Ecircle.configure do |config|
+  config.user     = "your@user.email.com"
+  config.realm    = "http://example.com"
+  config.password = "supersecret"
+end
+```
+
+the WSDL settings are assumed to be
+
+```
+wsdl.document = "http://webservices.ecircle-ag.com/soap/ecm.wsdl"
+wsdl.endpoint = "http://webservices.ecircle-ag.com/rpc"
+wsdl.namespace = "http://webservices.ecircleag.com/rpcns"
+```
+
+but can be overridden in the configuration
+
+```
+Ecircle.configure do |config|
+  config.wsdl.document = "http://example.com/?wsdl"
+  config.wsdl.endpoint = "http://blah.com"
+  config.wsdl.namespace = "some new namespace"
+end
+```
+
+Having configured the client, User retrieval is done via email or id:
+
+```
+user = Ecircle::User.find_by_email("some@email.com")
+user = Ecircle::User.find_by_id("1234131")
+```
+
+Logon is handled automagically by the Ecircle::Client, however the caller is responsible for
+retrying requests if a Ecircle::Client::NotLoggedIn exception is raised. There no need to
+explicitly call Ecircle::Client#logon, the exception notifies the client that it's not longer
+logged in and needs to login before the next request.
+
+Groups and Members
+------------------
+
+Having gotten a user, it's possible to find their memeberships of groups
+
+```
+groups = user.membership
+```
+
+Now a new user can be added to a group
+
+```
+member = groups.first.add_member Ecircle::User.create_by_email( "another@email.com" )
+```
+
+But if the member should be deleted from the group again
+
+```
+member.delete
+```
+

data/Rakefile

@@ -0,0 +1,53 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "ecircle_soap_client"
+  gem.homepage = "http://google.com/search?q=ecircle"
+  gem.license = "MIT"
+  gem.summary = %Q{Ecircle SOAP client for synchron API}
+  gem.description = %Q{See summary.}
+  gem.email = "gerrit.riessen@gmail.com"
+  gem.authors = ["Gerrit Riessen"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+  test.rcov_opts << '--exclude "gems/*"'
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "ecircle_soap_client #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.5

data/ecircle_soap_client.gemspec

@@ -0,0 +1,100 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "ecircle_soap_client"
+  s.version = "0.0.5"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Gerrit Riessen"]
+  s.date = "2011-09-01"
+  s.description = "See summary."
+  s.email = "gerrit.riessen@gmail.com"
+  s.extra_rdoc_files = [
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    ".rvmrc",
+    "Gemfile",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "ecircle_soap_client.gemspec",
+    "lib/ecircle/base.rb",
+    "lib/ecircle/client.rb",
+    "lib/ecircle/configuration.rb",
+    "lib/ecircle/group.rb",
+    "lib/ecircle/member.rb",
+    "lib/ecircle/message.rb",
+    "lib/ecircle/user.rb",
+    "lib/ecircle_soap_client.rb",
+    "start_pry_with_ecircle",
+    "test/.login.yml.sample",
+    "test/helper.rb",
+    "test/test_ecircle_soap_client.rb",
+    "test/test_ecircle_soap_client_group.rb",
+    "test/test_ecircle_soap_client_member.rb",
+    "test/test_ecircle_soap_client_message.rb",
+    "test/test_ecircle_soap_client_user.rb"
+  ]
+  s.homepage = "http://google.com/search?q=ecircle"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.10"
+  s.summary = "Ecircle SOAP client for synchron API"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rake>, ["= 0.8.7"])
+      s.add_runtime_dependency(%q<savon>, [">= 0"])
+      s.add_runtime_dependency(%q<nokogiri>, [">= 0"])
+      s.add_runtime_dependency(%q<multipart-post>, [">= 0"])
+      s.add_runtime_dependency(%q<uuidtools>, [">= 0"])
+      s.add_development_dependency(%q<pry>, [">= 0"])
+      s.add_development_dependency(%q<pry-doc>, [">= 0"])
+      s.add_development_dependency(%q<gist>, [">= 0"])
+      s.add_development_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.6.4"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+      s.add_development_dependency(%q<rr>, [">= 0"])
+      s.add_development_dependency(%q<cheat>, [">= 0"])
+    else
+      s.add_dependency(%q<rake>, ["= 0.8.7"])
+      s.add_dependency(%q<savon>, [">= 0"])
+      s.add_dependency(%q<nokogiri>, [">= 0"])
+      s.add_dependency(%q<multipart-post>, [">= 0"])
+      s.add_dependency(%q<uuidtools>, [">= 0"])
+      s.add_dependency(%q<pry>, [">= 0"])
+      s.add_dependency(%q<pry-doc>, [">= 0"])
+      s.add_dependency(%q<gist>, [">= 0"])
+      s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+      s.add_dependency(%q<rr>, [">= 0"])
+      s.add_dependency(%q<cheat>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rake>, ["= 0.8.7"])
+    s.add_dependency(%q<savon>, [">= 0"])
+    s.add_dependency(%q<nokogiri>, [">= 0"])
+    s.add_dependency(%q<multipart-post>, [">= 0"])
+    s.add_dependency(%q<uuidtools>, [">= 0"])
+    s.add_dependency(%q<pry>, [">= 0"])
+    s.add_dependency(%q<pry-doc>, [">= 0"])
+    s.add_dependency(%q<gist>, [">= 0"])
+    s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+    s.add_dependency(%q<rr>, [">= 0"])
+    s.add_dependency(%q<cheat>, [">= 0"])
+  end
+end
+

data/lib/ecircle/base.rb

@@ -0,0 +1,40 @@
+module Ecircle
+  class Base
+    attr_reader :id, :all_fields, :named_attrs
+
+    def id=(value)
+      @id = value
+    end
+
+    def [](name)
+      @all_fields[name.to_sym]
+    end
+
+    def initialize
+      @id, @all_fields, @named_attrs = "", {}, {}
+    end
+
+    def init_with_xml(element_name, xml_string)
+      n = Nokogiri.parse(xml_string)
+      @id = n.xpath("#{element_name}/@id" ).to_s
+      @all_fields = Hash[ n.xpath("//#{element_name}/*").collect do |a|
+                            [a.name.to_sym, a.children.first.to_s]
+                          end ]
+      @named_attrs = Hash[ n.xpath("#{element_name}/namedattr").collect do |a|
+                             [a.attributes["name"].value,
+                              a.children.empty? ? "" : a.children.first.to_s]
+                           end ]
+    end
+
+    # Handle all assignments, everything else is propagated to super.
+    def method_missing(method, *args, &block)
+      case method.to_s
+      when /\[\]=/ then super
+      when /(.+)=/
+        @all_fields[$1.to_sym] = args.first
+      else
+        super
+      end
+    end
+  end
+end

data/lib/ecircle/client.rb

@@ -0,0 +1,145 @@
+module Ecircle
+  class Client
+    attr_reader :session_token
+
+    LoginFailed      = Class.new(RuntimeError)
+    NotLoggedIn      = Class.new(RuntimeError)
+    PermissionDenied = Class.new(RuntimeError)
+
+    def initialize
+      @session_token = nil
+    end
+
+    class << self
+      # helper method for allowing clients to automatically retry requests to
+      # ecircle.
+      def attempt(retries = 2, &block)
+        begin
+          yield
+        rescue Ecircle::Client::NotLoggedIn => e
+          raise e unless retries > 0
+          attempt(retries - 1, &block)
+
+        rescue Ecircle::Client::PermissionDenied => e
+          raise e unless retries > 0
+          Ecircle.client.logon
+          attempt(retries - 1, &block)
+
+        rescue NoMethodError => e
+          raise e unless retries > 0
+          ## FIXME horrible hack because ecircle sometimes forgets that they
+          ## FIXME have a FindMembershipsByEmail method - old software with bad memory?
+          if e.message =~ /No such operation 'FindMembershipsByEmail'/
+            attempt(retries - 1, &block)
+          else
+            raise e
+          end
+        end
+      end
+    end
+
+    # This is the magic. All we do here is take the method name, camelcase it and
+    # then pass it to eCircle. It is assumed that the args array contains a hash
+    # as the first element. This then contains the arguments for the call. E.g.:
+    #    Ecircle.client.lookup_user_by_email :email => "willy@wonka.net"
+    # This will do a number of things:
+    #   1. login if session token is undefined
+    #   2. set the session parameter along with the email argument
+    #   3. check for specific eCircle exceptions and attempt to handle them.
+    def method_missing(method, *args, &block)
+      logon if @session_token.nil?
+
+      method_name, body = method.to_s.camelcase, args.first || {}
+      body[:session] = @session_token
+
+      response = begin
+                   client.request(method_name) { soap.body = body }
+                 rescue Savon::SOAP::Fault => e
+                   handle_savon_fault(e, :for_method => method)
+                 end
+
+      data = response.
+        body["#{method}_response".to_sym]["#{method}_return".to_sym]
+
+      if block_given?
+        yield(data)
+      else
+        case data
+        when /^[<]user/ then Ecircle::User.new(data)
+        when /^[<]member/ then Ecircle::Member.new(data)
+        when Hash
+          # If the response is only an empty element, the data will look like this:
+          # {:"@xmlns:ns1"=>"http://webservices.ecircleag.com/rpcns"}
+          # Return nil if we only have attributes.
+          data.all? { |key, value| key.to_s =~ /^@/ } ? nil : data
+        else
+          data
+        end
+      end
+    end
+
+    # Generate a Savon::Client to use for making requests. The configuration for the
+    # client is taken from the configure object.
+    def client
+      @client ||= Savon::Client.new do
+        wsdl.document  = Ecircle.configure.wsdl.document
+        wsdl.endpoint  = Ecircle.configure.wsdl.endpoint
+        wsdl.namespace = Ecircle.configure.wsdl.namespace
+      end
+    end
+
+    # Send logon request and store the session token if successful.
+    # The session token is then passed into each subsequent request to
+    # eCircle.
+    def logon
+      @session_token = (client.request :logon do
+        soap.body = {
+          :user   => Ecircle.configure.user,
+          :realm  => Ecircle.configure.realm,
+          :passwd => Ecircle.configure.password
+        }
+      end).body[:logon_response][:logon_return].to_s
+    rescue Savon::SOAP::Fault => e
+      @session_token = nil
+      raise LoginFailed, "Msg: #{e.message}"
+    end
+
+    # Invalid the session token and set it to nil.
+    # The session token automagically expires after 10 minutes of inactivity, so
+    # you might have to logout if methods are with NotLoggedIn
+    def logout
+      client.request :logout do
+        soap.body = {
+          :session => @session_token
+        }
+      end
+    ensure
+      @session_token = nil
+    end
+
+    private
+
+    def handle_savon_fault(exception, opts = {})
+      method = opts[:for_method] || "UNKNOWN"
+
+      case exception.message
+
+      when /No such operation/ then
+        raise NoMethodError, "#{method} (by way of #{exception.message})"
+
+      when /Not authenticated/, /LoginException/ then
+        @session_token = nil # automagically login with the next call.
+        raise NotLoggedIn, exception.message
+
+      when /Authorisation failure/, /Permission Problem/ then
+        # This is not a login issue per-se, this is an authorisation
+        # issue, so the client must decide whether to logon again to
+        # attempt to resolve the issue.
+        raise PermissionDenied, exception.message
+
+      else
+        raise exception
+      end
+    end
+  end
+end