rews 0.1.0 → 0.2.0

data/README.rdoc

@@ -35,6 +35,12 @@ to use :
 
 == Install
 
+  to use NTLM authentication, you need versions of httpclient and ntlm-http 
+  gems with fixes for NTLM authentication
+
+  * httpclient branch ntlm_domain : https://github.com/mccraigmccraig/httpclient/tree/ntlm_domain
+  * ntlm-http branch fix_unicode : https://github.com/trampoline/ntlm-http/tree/fix_unicode
+
   gem install rews
 
 == Note on Patches/Pull Requests

data/Rakefile

@@ -11,11 +11,12 @@ begin
     gem.homepage = "http://github.com/trampoline/rews"
     gem.authors = ["Trampoline Systems Ltd"]
     gem.add_dependency "savon", ">= 0.8.6"
-    gem.add_dependency "ntlm-http", ">= 0.1.1"
+    gem.add_dependency "ntlm-http", ">= 0.1.1.1"
     gem.add_dependency "httpclient", ">= 2.1.6.1.1"
     gem.add_dependency "fetch_in", ">= 0.2.0"
     gem.add_development_dependency "rspec", ">= 1.2.9"
     gem.add_development_dependency "rr", ">= 0.10.5"
+    gem.add_development_dependency "nokogiri", ">= 1.4.4"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/rews/client.rb

@@ -0,0 +1,48 @@
+module Rews
+  class Client
+    attr_reader :client
+    attr_accessor :logdev
+
+    # create a +Client+ to access Exchange Web Services
+    # * using NTLM authentication
+    #  Rews::Client.new('https://exchange.foo.com/EWS/Exchange.asmx', :ntlm, 'DOMAIN\\user', 'password')
+    # * using basic authentication
+    #  Rews::Client.new('https://exchange.foo.com/EWS/Exchange.asmx', :basic, 'DOMAIN\\user', 'password')
+    def initialize(endpoint, auth_type, user, password)
+      @endpoint=endpoint
+      @auth_type = auth_type
+      @user=user
+      @password=password
+      @client = Savon::Client.new do
+        wsdl.endpoint = endpoint
+        wsdl.namespace = SCHEMA_MESSAGES
+        
+        http.auth.ssl.verify_mode = :none
+        http.auth.send(auth_type, user, password)
+      end
+    end
+
+    def inspect
+      "#<#{self.class} @endpoint=#{@endpoint}, @auth_type=#{@auth_type}, @user=#{@user}, @password=#{@password}>"
+    end
+
+    # get a <tt>Folder::DistinguishedFolderId</tt> referencing one of the named top-level Folders in an Exchange mailbox
+    # * get a folder from the default mailbox
+    #  client.distinguished_folder_id('inbox')
+    # * get a folder from another mailbox
+    #  client.distinguished_folder_id('inbox', 'foo@bar.com')
+    def distinguished_folder_id(id, mailbox_email=nil)
+      Folder::DistinguishedFolderId.new(client, id, mailbox_email)
+    end
+
+    # yield a +Logger+ if +logdev+ has been set
+    def log
+      yield logger if @logdev
+    end
+
+    def logger
+      return @logger if @logger
+      @logger = Logger.new(@logdev) if @logdev
+    end
+  end
+end

data/lib/rews/folder.rb

@@ -1,24 +1,41 @@
 module Rews
   module Folder
+
+    # represents a Folder in a mailbox on an Exchange server
     class Folder
       attr_reader :client
       attr_reader :folder_id
       attr_reader :attributes
 
       def initialize(client, folder)
+        @client = client
         @folder_id = VanillaFolderId.new(client, folder[:folder_id])
         @attributes = folder
       end
 
+      def ==(other)
+        other.is_a?(Folder) &&
+          @client == other.client &&
+          @folder_id == other.folder_id &&
+          @attributes == other.attributes
+      end
+
+      # access the +Folder+ +attributes+
       def [](key)
         @attributes[key]
       end
 
+      # keys of the +Folder+ +attributes+
       def keys
         @attributes.keys
       end
+
+      def inspect
+        "#<#{self.class} @folder_id=#{@folder_id.inspect}, @attributes=#{@attributes.inspect}>"
+      end
     end
 
+    # <tt>find_*</tt> methods on <tt>Folder::BaseFolderId</tt> return a +FindResult+
     class FindResult
       VIEW_ATTRS = [:includes_last_item_in_range,
                     :indexed_paging_offset,
@@ -27,6 +44,8 @@ module Rews
       VIEW_ATTRS.each do |attr|
         attr_reader attr
       end
+
+      # the +result+ of the +find_*+ call
       attr_reader :result
 
       def initialize(view, &proc)
@@ -36,19 +55,28 @@ module Rews
         @result = proc.call(view) if proc
       end
 
+      # count of items in the +result+
       def length
         result.length
       end
 
+      # alias for +length+
       def size
         result.size
       end
 
+      # access an element from +result+
       def [](key)
         result[key]
       end
+
+      def inspect
+        attrs = VIEW_ATTRS.map{|attr| "@#{attr}=#{self.send(attr)}"}.join(", ")
+        "#<#{self.class} #{attrs}, @result=#{@result.inspect}>"
+      end
     end
 
+    # Identifies a Folder
     class BaseFolderId
       include Util
       
@@ -63,6 +91,7 @@ module Rews
         :indexed_page_folder_view=>View::INDEXED_PAGE_VIEW_OPTS,
         :folder_shape=>Shape::FOLDER_SHAPE_OPTS}
 
+      # find <tt>Folder::Folder</tt>s within a <tt>Folder::Folder</tt>
       def find_folder(opts={})
         opts = check_opts(FIND_FOLDER_OPTS, opts)
 
@@ -76,7 +105,7 @@ module Rews
             xml << Restriction.new(opts[:restriction]).to_xml if opts[:restriction]
             
             xml.wsdl :ParentFolderIds do
-              xml << Gyoku.xml(self.to_xml_hash)
+              xml << self.to_xml
             end
             soap.body = xml.target!
           end
@@ -91,6 +120,7 @@ module Rews
         end
       end
 
+      # find <tt>Folder::FolderIds</tt>s within a <tt>Folder::FolderIds</tt>
       def find_folder_id(opts={})
         opts = check_opts(FIND_FOLDER_OPTS, opts)
 
@@ -108,7 +138,7 @@ module Rews
         :indexed_page_item_view=>View::INDEXED_PAGE_VIEW_OPTS,
         :item_shape=>Shape::ITEM_SHAPE_OPTS}
 
-      # find message-ids in a folder
+      # find <tt>Item::Item</tt>s in a folder
       def find_item(opts={})
         opts = check_opts(FIND_ITEM_OPTS, opts)
 
@@ -124,7 +154,7 @@ module Rews
             xml << SortOrder.new(opts[:sort_order]).to_xml if opts[:sort_order]
 
             xml.wsdl :ParentFolderIds do
-              xml << Gyoku.xml(self.to_xml_hash)
+              xml << self.to_xml
             end
 
             soap.body = xml.target!
@@ -136,6 +166,7 @@ module Rews
         end
       end
 
+      # find <tt>Item::ItemIds</tt>s in a folder
       def find_item_id(opts={})
         opts = check_opts(FIND_ITEM_OPTS, opts)
 
@@ -152,7 +183,9 @@ module Rews
         :ignore_change_keys=>nil
       }
 
-      # get a bunch of messages in one api hit
+      # retrieve a bunch of <tt>Item::Item</tt>s in one API hit.
+      # takes a list of <tt>Item::ItemId</tt>s, or a list of <tt>Item::Item</tt>, 
+      # or a <tt>Folder::FindResult</tt> and options to specify +Shape::ItemShape+
       def get_item(message_ids, opts={})
         opts = check_opts(GET_ITEM_OPTS, opts)
         message_ids = message_ids.result if message_ids.is_a?(FindResult)
@@ -166,7 +199,8 @@ module Rews
             xml << Shape::ItemShape.new(opts[:item_shape]||{}).to_xml
             xml.wsdl :ItemIds do
               message_ids.each do |mid|
-                xml << Gyoku.xml(mid.to_xml_hash(opts[:ignore_change_keys]))
+                mid = mid.item_id if mid.is_a?(Item::Item)
+                xml << mid.to_xml(opts[:ignore_change_keys])
               end
             end
 
@@ -181,6 +215,9 @@ module Rews
         :ignore_change_keys=>false
       }
 
+      # delete a bunch of Items in one API hit.
+      # takes a list of <tt>Item::ItemId</tt>s, or a list of <tt>Item::Item</tt>, 
+      # or a <tt>Folder::FindResult</tt> and options to specify DeleteType
       def delete_item(message_ids, opts={})
         opts = check_opts(DELETE_ITEM_OPTS, opts)
         message_ids = message_ids.result if message_ids.is_a?(FindResult)
@@ -193,7 +230,8 @@ module Rews
 
             xml.wsdl :ItemIds do
               message_ids.each do |mid|
-                xml << Gyoku.xml(mid.to_xml_hash(opts[:ignore_change_keys]))
+                mid = mid.item_id if mid.is_a?(Item::Item)
+                xml << mid.to_xml(opts[:ignore_change_keys])
               end
             end
 
@@ -204,8 +242,12 @@ module Rews
       end
     end
 
+    # identifies a regular (non-distinguished) Folder on an Exchange server
     class VanillaFolderId < BaseFolderId
+      # the Id of the Folder
       attr_reader :id
+
+      # +change_key+ identifies a specific version of the Folder
       attr_reader :change_key
 
       def initialize(client, folder_id)
@@ -215,30 +257,33 @@ module Rews
         raise "no id" if !@id
       end
 
-      def to_xml_hash
-        if change_key
-          {
-            "t:FolderId"=>"",
-            :attributes! => {
-              "t:FolderId" => {
-                "Id" => id.to_s,
-                "ChangeKey" => change_key.to_s}}}
-        else
-          {
-            "t:FolderId"=>"",
-            :attributes! => {
-              "t:FolderId" => {
-                "Id" => id.to_s}}}
-        end
+      def ==(other)
+        other.is_a?(VanillaFolderId) &&
+          @client == other.client &&
+          @id == other.id &&
+          @change_key == other.change_key
+      end
+
+      def to_xml
+        xml = Builder::XmlMarkup.new
+        attrs = {:Id=>id.to_s}
+        attrs[:ChangeKey] = change_key.to_s if change_key
+        xml.t :FolderId, attrs
+        xml.target!
       end
 
       def inspect
-        "#{self.class}(id: #{id}, change_key: #{change_key})"
+        "#<#{self.class} @id=#{id}, @change_key=#{change_key}>"
       end
     end
 
+    # identifies a DistinguishedFolder in a mailbox on an Exchange server.
+    # the <tt>Client.distinguished_folder_id</tt> method returns <tt>DistinguishedFolderId</tt>s
     class DistinguishedFolderId < BaseFolderId
+      # the Id of the DistinguishedFolder e.g. <tt>"inbox"</tt>
       attr_reader :id
+
+      # the email address of the mailbox containing the DistinguishedFolder
       attr_reader :mailbox_email
 
       def initialize(client, id, mailbox_email=nil)
@@ -248,26 +293,27 @@ module Rews
         raise "no id" if !@id
       end
 
-      def to_xml_hash
-        {
-          "t:DistinguishedFolderId"=>mailbox_xml_hash,
-          :attributes! => {"t:DistinguishedFolderId"=>{"Id"=>id}}}
+      def ==(other)
+        other.is_a?(DistinguishedFolderId) &&
+          @client = other.client &&
+          @id = other.id &&
+          @mailbox_email = other.mailbox_email
       end
 
-      def inspect
-        "#{self.class}(id: #{id}, mailbox_email: #{mailbox_email})"
+      def to_xml
+        xml = Builder::XmlMarkup.new
+        xml.t :DistinguishedFolderId, :Id=>id do
+          if mailbox_email
+            xml.t :Mailbox do
+              xml.t :EmailAddress, mailbox_email
+            end
+          end
+        end
+        xml.target!
       end
 
-      private
-
-      def mailbox_xml_hash
-        if mailbox_email
-          {
-            "t:Mailbox"=>{
-              "t:EmailAddress"=>mailbox_email}}
-        else
-          ""
-        end
+      def inspect
+        "#<#{self.class} @id=#{id}, @mailbox_email=#{mailbox_email}>"
       end
     end
   end

data/lib/rews/item.rb

@@ -20,6 +20,7 @@ module Rews
       end.flatten
     end
 
+    # represents an Item from a mailbox on an Exchange server
     class Item
       attr_reader :client
       attr_reader :item_id
@@ -27,25 +28,45 @@ module Rews
       attr_reader :attributes
       
       def initialize(client, item_class, attributes)
+        @client = client
         @item_id = ItemId.new(client, attributes[:item_id])
         @item_class = item_class
         @attributes = attributes
       end
 
+      def ==(other)
+        other.is_a?(Item) &&
+          @client == other.client &&
+          @item_id == other.item_id &&
+          @item_class == other.item_class &&
+          @attributes == other.attributes
+      end
+
+      # access the Item attributes
       def [](key)
         @attributes[key]
       end
-
+      
+      # names of the Item attributes
       def keys
         @attributes.keys
       end
+
+      def inspect
+        "#<#{self.class} @item_class=#{@item_class}, @item_id=#{@folder_id.inspect}, @attributes=#{@attributes.inspect}>"
+      end
     end
 
+    # identifies an Item
     class ItemId
       include Util
 
       attr_reader :client
+
+      # the +Id+ of the Item
       attr_reader :id
+
+      # the version of the Item
       attr_reader :change_key
       
       def initialize(client, item_id)
@@ -55,11 +76,18 @@ module Rews
         raise "no id" if !@id
       end
 
+      def ==(other)
+        @client == other.client &&
+          @id == other.id &&
+          @change_key == other.change_key
+      end
+
       GET_ITEM_OPTS = {
         :item_shape=>Shape::ITEM_SHAPE_OPTS,
         :ignore_change_keys=>nil
       }
 
+      # get the <tt>Item::Item</tt> identified by this <tt>Item::ItemId</tt>
       def get_item(opts={})
         opts = check_opts(GET_ITEM_OPTS, opts)
         r = with_error_check(client, :get_item_response,:response_messages,:get_item_response_message) do
@@ -70,7 +98,7 @@ module Rews
             
             xml << Shape::ItemShape.new(opts[:item_shape]||{}).to_xml
             xml.wsdl :ItemIds do
-              xml << Gyoku.xml(self.to_xml_hash(opts[:ignore_change_keys]))
+              xml << self.to_xml(opts[:ignore_change_keys])
             end
             
             soap.body = xml.target!
@@ -84,6 +112,7 @@ module Rews
         :ignore_change_keys=>false
       }
 
+      # delete the Item from the server
       def delete_item(opts={})
         opts = check_opts(DELETE_ITEM_OPTS, opts)
         r = with_error_check(client, :delete_item_response, :response_messages, :delete_item_response_message) do
@@ -93,7 +122,7 @@ module Rews
             xml = Builder::XmlMarkup.new
             
             xml.wsdl :ItemIds do
-              xml << Gyoku.xml(self.to_xml_hash(opts[:ignore_change_keys]))
+              xml << self.to_xml(opts[:ignore_change_keys])
             end
             
             soap.body = xml.target!
@@ -102,25 +131,16 @@ module Rews
         true
       end
 
-      def to_xml_hash(ignore_change_key=false)
-        if change_key && !ignore_change_key
-          {
-            "t:ItemId"=>"",
-            :attributes! => {
-              "t:ItemId" => {
-                "Id" => id.to_s,
-                "ChangeKey" => change_key.to_s}}}
-        else
-          {
-            "t:ItemId"=>"",
-            :attributes! => {
-              "t:ItemId" => {
-                "Id" => id.to_s}}}
-        end
+      def to_xml(ignore_change_key=false)
+        xml = Builder::XmlMarkup.new
+        attrs = {:Id=>id.to_s}
+        attrs[:ChangeKey] = change_key.to_s if change_key && !ignore_change_key
+        xml.t :ItemId, attrs
+        xml.target!
       end
 
       def inspect
-        "#{self.class}(id: #{id}, change_key: #{change_key})"
+        "#<#{self.class} @id=#{id}, @change_key=#{change_key}>"
       end
     end
   end

data/lib/rews/restriction.rb

@@ -1,8 +1,11 @@
-# takes restrictions written in Ruby s-expressions and 
-# outputs Exchange Web Services Restriction XML
-#
-#
 module Rews
+  # models Restrictions for <tt>find_*</tt> operations
+  # on <tt>Folder::BaseFolderId</tt>
+  #
+  # takes restrictions written in Ruby s-expressions and 
+  # outputs Exchange Web Services Restriction XML. e.g.
+  #
+  # <tt>[[:and, [:==, "item:Subject", "hello"], [:>=, "item:DateTimeSent", DateTime.parse("2011-03-16T15:57:37+00:00")]]</tt>
   class Restriction
 
     attr_reader :expr
@@ -12,7 +15,7 @@ module Rews
     end
 
     def inspect
-      "#{self.class}: #{@expr.inspect}"
+      "#<#{self.class} @expr=#{@expr.inspect}>"
     end
 
     def to_xml
@@ -81,7 +84,9 @@ module Rews
       }
       def write_logical(xml, expr)
         xml.t LOGICAL_OPS[expr[0]] do
-          write_xml(xml ,expr[1..-1])
+          expr[1..-1].each do |clause|
+            Xml::write_expr(xml, clause)
+          end
         end
       end
     end

data/lib/rews/shape.rb

@@ -24,9 +24,15 @@ module Rews
       end
     end
 
+    # models ItemShape and FolderShape used in <tt>Folder::BaseFolderId.find_*</tt> and 
+    # <tt>Folder::BaseFolderId.get_*</tt> methods
     class Base
       include Util
       attr_reader :shape
+
+      def inspect
+        "#<#{self.class} @shape=#{@shape}>"
+      end
     end
 
     ITEM_SHAPE_OPTS = {
@@ -35,6 +41,8 @@ module Rews
       :additional_properties=>nil
     }
 
+    # models ItemShape used in <tt>Folder::BaseFolderId.find_item</tt> and
+    # <tt>Folder::BaseFolderId.get_item</tt> methods
     class ItemShape < Base
       def initialize(shape)
         @shape = check_opts(ITEM_SHAPE_OPTS, shape)
@@ -54,6 +62,7 @@ module Rews
       :additional_properties=>nil
     }
 
+    # models +FolderShape+ used in <tt>Folder::BaseFolderId.find_folder</tt> method
     class FolderShape < Base
       def initialize(shape)
         @shape = check_opts(FOLDER_SHAPE_OPTS, shape)

data/lib/rews/sort_order.rb

@@ -1,6 +1,10 @@
-# takes sort_orders written in Ruby s-expressions and
-# outputs EWS SortOrder XML
 module Rews
+  # models SortOrder used in <tt>Folder::BaseFolderId.find_*</tt> methods
+  #
+  # takes sort_orders written in Ruby s-expressions and
+  # outputs EWS SortOrder XML e.g.
+  #
+  # <tt>[["item:DateTimeReceived", "Ascending"], ["item:Size", "Descending"]]</tt>
   class SortOrder
     attr_reader :expr
 
@@ -9,7 +13,7 @@ module Rews
     end
 
     def inspect
-      "#{self.class}: #{@expr.inspect}"
+      "#<#{self.class} @expr=#{@expr.inspect}>"
     end
     
     def to_xml

data/lib/rews/util.rb

@@ -6,10 +6,10 @@ module Rews
 
     # validates an options hash against a constraints hash
     # in the constraints hash :
-    # - keys ending in ! indicate option is required
-    # - keys not ending in ! indicate option is not required
-    # - non-nil values provide defaults
-    # - hash values provide constraints for sub-hashes
+    # * keys ending in ! indicate option is required
+    # * keys not ending in ! indicate option is not required
+    # * non-nil values provide defaults
+    # * hash values provide constraints for sub-hashes
     def check_opts(constraints, opts={}, prefix=nil)
       required_keys = Hash[constraints.keys.select{|k| k.to_s[-1..-1] == '!'}.map{|k| [strip_bang(k),k]}]
       optional_keys = constraints.keys.select{|k| k.to_s[-1..-1] != '!'}
@@ -30,10 +30,11 @@ module Rews
       raise "required options not given: #{required_keys.keys.map{|k| [prefix,k].compact.join('.')}.join(", ")}" if required_keys.size>0
       
       # defaults
-      optional_keys.each{|k| opts[k] = constraints[k] if !constraints[k].is_a?(Hash)}
+      optional_keys.each{|k| opts[k] = constraints[k] if constraints[k] && !constraints[k].is_a?(Hash)}
       opts
     end
 
+    # strip a ! from the end of a +String+ or +Symbol+
     def strip_bang(k)
       if k.is_a? Symbol
         k.to_s[0...-1].to_sym
@@ -42,14 +43,19 @@ module Rews
       end
     end
 
+    # camel-case a +String+
     def camelize(s)
       s.split('_').map(&:capitalize).join
     end
 
+    # camel-case the keys of a +Hash+
     def camel_keys(h)
       Hash[h.map{|k,v| [camelize(k.to_s), v]}]
     end
 
+    # check the response codes of an Exchange Web Services request.
+    # the supplied block makes a SOAP request, and the response is parsed
+    # out and checked
     def with_error_check(client, *response_msg_keys)
       raise "no block" if !block_given?
 
@@ -69,6 +75,7 @@ module Rews
       statuses
     end
 
+    # check the status of the response of a single part of a multi-part request
     def single_error_check(client, status)
       begin
         response_class = status[:response_class]
@@ -77,9 +84,9 @@ module Rews
       end
 
       if status[:response_class] == "Error"
-        return "Rews: #{status[:response_code]} - #{status[:message_text]}"
+        return "#{status[:response_code]} - #{status[:message_text]}"
       elsif status[:response_class] == "Warning"
-        client.log{|logger| logger.warn("#{status[:message_text]}")}
+        client.log{|logger| logger.warn("#{status[:response_code]} - #{status[:message_text]}")}
       end
     end
   end

data/lib/rews/view.rb

@@ -1,4 +1,6 @@
 module Rews
+  # models IndexedPageItemView and IndexedPageFolderView definitions used by
+  # <tt>Folder::BaseFolderId.find_*</tt> methods
   module View
     module Xml
       module_function
@@ -16,10 +18,15 @@ module Rews
       include Util
       
       attr_reader :view
+
+      def inspect
+        "#<#{self.class} @view=#{@view.inspect}>"
+      end
     end
 
     INDEXED_PAGE_VIEW_OPTS = {:max_entries_returned=>nil, :offset=>0, :base_point=>:Beginning}
 
+    # models the IndexedPageItemView used in <tt>Folder::BaseFolderId.find_item</tt> method
     class IndexedPageItemView < Base
       def initialize(view)
         @view = check_opts(INDEXED_PAGE_VIEW_OPTS, view)
@@ -30,6 +37,7 @@ module Rews
       end
     end
 
+    # models the IndexedPageFolderView used in <tt>Folder::BaseFolderId.find_folder</tt> methods
     class IndexedPageFolderView < Base
       def initialize(view)
         @view = check_opts(INDEXED_PAGE_VIEW_OPTS, view)