exchanger 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Edgars Beigarts
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,53 @@
+Exchanger
+=========
+
+Ruby library for accessing Microsoft Exchange using Exchange Web Services.
+This library tries to make creating and updating items as easy as possible.
+It will keep track of changed properties and will update only them.
+
+Supported operations
+====================
+
+* FindItem, GetItem, CreateItem, UpdateItem
+* FindFolder, GetFolder
+
+
+Installing
+==========
+
+    gem install exchanger
+
+Configuration
+=============
+
+    Exchanger.configure do |config|
+      config.endpoint = "https://domain.com/EWS/Exchanger.asmx"
+      config.username = "username"
+      config.password = "password"
+    end
+
+or configure from YAML
+
+    Exchanger::Config.instance.from_hash(YAML.load_file("#{Rails.root}/config/exchanger.yml")[Rails.env])
+
+Examples
+========
+
+Creating and updating contacts
+------------------------------
+
+    folder = Exchanger::Folder.find(:contacts)
+    contact = folder.new_contact
+    contact.given_name = "Edgars"
+    contact.surname = "Beigarts"
+    contact.email_addresses = [ Exchanger::EmailAddress.new(:key => "EmailAddress1", :text => "me@domain.com") ]
+    contact.phone_numbers = [ Exchanger::PhoneNumber.new(:key => "MobilePhone", :text => "+371 80000000") ]
+    contact.save # CreateItem operation
+    contact.company_name = "Tieto"
+    contact.save # UpdateItem operation
+
+Alternatives
+============
+
+* [github.com/jrun/ews-api](http://github.com/jrun/ews-api)
+* [github.com/zenchild/Viewpoint](http://github.com/zenchild/Viewpoint)

data/lib/exchanger.rb

@@ -0,0 +1,79 @@
+require "singleton"
+require "delegate"
+require "base64"
+
+require "active_support/core_ext"
+require "nokogiri"
+require "httpclient"
+require "net/ntlm"
+
+require "exchanger/config"
+require "exchanger/client"
+require "exchanger/boolean"
+require "exchanger/field"
+require "exchanger/dirty"
+require "exchanger/attributes"
+require "exchanger/persistence"
+
+# Elements
+require "exchanger/element"
+require "exchanger/elements/identifier"
+require "exchanger/elements/mailbox"
+require "exchanger/elements/single_recipient"
+require "exchanger/elements/attendee"
+require "exchanger/elements/complete_name"
+# Entry elements
+require "exchanger/elements/entry"
+require "exchanger/elements/email_address"
+require "exchanger/elements/phone_number"
+require "exchanger/elements/physical_address"
+require "exchanger/elements/im_address"
+# Folder elements
+require "exchanger/elements/base_folder"
+require "exchanger/elements/folder"
+require "exchanger/elements/calendar_folder"
+require "exchanger/elements/contacts_folder"
+require "exchanger/elements/tasks_folder"
+require "exchanger/elements/search_folder"
+# Item elements
+require "exchanger/elements/item"
+require "exchanger/elements/message"
+require "exchanger/elements/calendar_item"
+require "exchanger/elements/contact"
+require "exchanger/elements/meeting_message"
+require "exchanger/elements/meeting_request"
+require "exchanger/elements/meeting_response"
+require "exchanger/elements/meeting_cancellation"
+require "exchanger/elements/task"
+require "exchanger/elements/distribution_list"
+
+# Operations
+require "exchanger/operation"
+require "exchanger/operations/get_folder"
+require "exchanger/operations/find_folder"
+require "exchanger/operations/get_item"
+require "exchanger/operations/find_item"
+require "exchanger/operations/create_item"
+require "exchanger/operations/update_item"
+require "exchanger/operations/resolve_names"
+require "exchanger/operations/expand_dl"
+
+module Exchanger
+  NS = {
+    "xsi"  => "http://www.w3.org/2001/XMLSchema-instance",
+    "xsd"  => "http://www.w3.org/2001/XMLSchema",
+    "soap" => "http://schemas.xmlsoap.org/soap/envelope/",
+    "m"    => "http://schemas.microsoft.com/exchange/services/2006/messages",
+    "t"    => "http://schemas.microsoft.com/exchange/services/2006/types"
+  }
+
+  class << self
+    # The Exchanger +Config+ singleton instance.
+    def configure
+      config = Config.instance
+      block_given? ? yield(config) : config
+    end
+    
+    alias :config :configure
+  end
+end

data/lib/exchanger/attributes.rb

@@ -0,0 +1,61 @@
+module Exchanger
+  module Attributes
+    def attributes=(values = {})
+      values.each do |name, value|
+        write_attribute(name, value)
+      end
+    end
+
+    # Return the attributes hash with indifferent access.
+    def attributes
+      @attributes.with_indifferent_access
+    end
+
+    # TODO: Add typecasting
+    # Read a value from the +Document+ attributes. If the value does not exist
+    # it will return nil.
+    def read_attribute(name)
+      name = name.to_s
+      value = @attributes[name]
+      accessed(name, value)
+    end
+
+    # TODO: Add typecasting
+    def write_attribute(name, value)
+      name = name.to_s
+      modify(name, @attributes[name], value)
+    end
+
+    def identifier
+      if self.class.identifier_name
+        @identifier ||= self.send(self.class.identifier_name)
+        @identifier.tag_name = self.class.identifier_name.to_s.camelize if @identifier
+        @identifier
+      end
+    end
+
+    def id
+      identifier && identifier.id
+    end
+
+    def change_key
+      identifier && identifier.change_key
+    end
+
+    # Override respond_to? so it responds properly for dynamic attributes
+    def respond_to?(name)
+      (@attributes && @attributes.has_key?(name.to_s)) || super
+    end
+
+    # Used for allowing accessor methods for dynamic attributes
+    def method_missing(name, *args)
+      attr = name.to_s.sub("=", "")
+      return super unless attributes.has_key?(attr)
+      if name.to_s.ends_with?("=")
+        write_attribute(attr, *args)
+      else
+        read_attribute(attr)
+      end
+    end
+  end
+end

data/lib/exchanger/boolean.rb

@@ -0,0 +1,4 @@
+module Exchanger
+  class Boolean
+  end
+end

data/lib/exchanger/client.rb

@@ -0,0 +1,19 @@
+module Exchanger
+  # SOAP Client for Exhange Web Services
+  class Client
+    delegate :endpoint, :timeout, :username, :password, :debug, :to => "Exchanger.config"
+
+    def initialize
+      @client = HTTPClient.new
+      @client.debug_dev = STDERR if debug
+      @client.set_auth nil, username, password if username
+    end
+
+    # Does the actual HTTP level interaction.
+    def request(post_body, headers)
+      # @client.ssl_config.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      response = @client.post(endpoint, post_body, headers)
+      return { :status => response.status, :body => response.content, :content_type => response.contenttype }
+    end
+  end
+end

data/lib/exchanger/config.rb

@@ -0,0 +1,32 @@
+module Exchanger
+  class Config
+    include Singleton
+
+    attr_accessor :endpoint, :timeout, :username, :password, :debug
+
+    def initialize
+      reset
+    end
+
+    # Reset the configuration options to the defaults.
+    def reset
+      @endpoint = nil
+      @timeout = 5
+      @username = nil
+      @password = nil
+      @debug = false
+    end
+
+    # Configure Exchanger client from a hash. This is usually called after parsing a
+    # yaml config file such as exchanger.yml.
+    #
+    # Example:
+    #
+    # <tt>Exchanger::Config.instance.from_hash({})</tt>
+    def from_hash(settings)
+      settings.each do |name, value|
+        send("#{name}=", value) if respond_to?("#{name}=")
+      end
+    end
+  end
+end

data/lib/exchanger/dirty.rb

@@ -0,0 +1,239 @@
+module Exchanger
+  module Dirty
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Gets the changes for a specific field.
+    #
+    # Example:
+    #
+    #   person = Person.new(:title => "Sir")
+    #   person.title = "Madam"
+    #   person.attribute_change("title") # [ "Sir", "Madam" ]
+    #
+    # Returns:
+    #
+    # An +Array+ containing the old and new values.
+    def attribute_change(name)
+      modifications[name]
+    end
+
+    # Determines if a specific field has chaged.
+    #
+    # Example:
+    #
+    #   person = Person.new(:title => "Sir")
+    #   person.title = "Madam"
+    #   person.attribute_changed?("title") # true
+    #
+    # Returns:
+    #
+    # +true+ if changed, +false+ if not.
+    def attribute_changed?(name)
+      modifications.include?(name)
+    end
+
+    # Gets the old value for a specific field.
+    #
+    # Example:
+    #
+    #   person = Person.new(:title => "Sir")
+    #   person.title = "Madam"
+    #   person.attribute_was("title") # "Sir"
+    #
+    # Returns:
+    #
+    # The old field value.
+    def attribute_was(name)
+      change = modifications[name]
+      change ? change[0] : nil
+    end
+
+    # Gets the names of all the fields that have changed in the document.
+    #
+    # Example:
+    #
+    #   person = Person.new(:title => "Sir")
+    #   person.title = "Madam"
+    #   person.changed # returns [ "title" ]
+    #
+    # Returns:
+    #
+    # An +Array+ of changed field names.
+    def changed
+      modifications.keys
+    end
+
+    # Alerts to whether the document has been modified or not.
+    #
+    # Example:
+    #
+    #   person = Person.new(:title => "Sir")
+    #   person.title = "Madam"
+    #   person.changed? # returns true
+    #
+    # Returns:
+    #
+    # +true+ if changed, +false+ if not.
+    def changed?
+      !modifications.empty?
+    end
+
+    # Gets all the modifications that have happened to the object as a +Hash+
+    # with the keys being the names of the fields, and the values being an
+    # +Array+ with the old value and new value.
+    #
+    # Example:
+    #
+    #   person = Person.new(:title => "Sir")
+    #   person.title = "Madam"
+    #   person.changes # returns { "title" => [ "Sir", "Madam" ] }
+    #
+    # Returns:
+    #
+    # A +Hash+ of changes.
+    def changes
+      modifications
+    end
+
+    # Call this method after save, so the changes can be properly switched.
+    #
+    # Example:
+    #
+    # <tt>person.move_changes</tt>
+    def move_changes
+      @previous_modifications = modifications.dup
+      @modifications = {}
+    end
+
+    # Gets all the modifications that have happened to the object before the
+    # object was saved.
+    #
+    # Example:
+    #
+    #   person = Person.new(:title => "Sir")
+    #   person.title = "Madam"
+    #   person.save!
+    #   person.previous_changes # returns { "title" => [ "Sir", "Madam" ] }
+    #
+    # Returns:
+    #
+    # A +Hash+ of changes before save.
+    def previous_changes
+      @previous_modifications
+    end
+
+    # Resets a changed field back to its old value.
+    #
+    # Example:
+    #
+    #   person = Person.new(:title => "Sir")
+    #   person.title = "Madam"
+    #   person.reset_attribute!("title")
+    #   person.title # "Sir"
+    #
+    # Returns:
+    #
+    # The old field value.
+    def reset_attribute!(name)
+      value = attribute_was(name)
+      if value
+        @attributes[name] = value
+        modifications.delete(name)
+      end
+    end
+
+    # Sets up the modifications hash. This occurs just after the document is
+    # instantiated.
+    #
+    # Example:
+    #
+    # <tt>document.setup_notifications</tt>
+    def setup_modifications
+      @accessed ||= {}
+      @modifications ||= {}
+      @previous_modifications ||= {}
+    end
+
+    # Reset all modifications for the document. This will wipe all the marked
+    # changes, but not reset the values.
+    #
+    # Example:
+    #
+    # <tt>document.reset_modifications</tt>
+    def reset_modifications
+      @accessed = {}
+      @modifications = {}
+    end
+
+    protected
+
+    # Audit the original value for a field that can be modified in place.
+    #
+    # Example:
+    #
+    # <tt>person.accessed("aliases", [ "007" ])</tt>
+    def accessed(name, value)
+      @accessed ||= {}
+      @accessed[name] = value.dup if (value.is_a?(Array) || value.is_a?(Hash)) && !@accessed.has_key?(name)
+      value
+    end
+
+    # Get all normal modifications plus in place potential changes.
+    # Also checks changes in array attributes with +Element+ objects.
+    #
+    # Example:
+    #
+    # <tt>person.modifications</tt>
+    #
+    # Returns:
+    #
+    # All changes to the document.
+    def modifications
+      @accessed.each_pair do |field, value|
+        current = @attributes[field]
+        if current != value || (current.is_a?(Array) &&
+            current.any? { |v| v.respond_to?(:changed?) && v.changed? })
+          @modifications[field] = [ value, current ]
+        end
+      end
+      @accessed.clear
+      @modifications
+    end
+
+    # Audit the change of a field's value.
+    #
+    # Example:
+    #
+    # <tt>person.modify("name", "Jack", "John")</tt>
+    def modify(name, old_value, new_value)
+      @attributes[name] = new_value
+      if @modifications && (old_value != new_value)
+        original = @modifications[name].first if @modifications[name]
+        @modifications[name] = [ (original || old_value), new_value ]
+      end
+    end
+
+    module ClassMethods #:nodoc:
+      # Add the dynamic dirty methods. These are custom methods defined on a
+      # field by field basis that wrap the dirty attribute methods.
+      #
+      # Example:
+      #
+      #   person = Person.new(:title => "Sir")
+      #   person.title = "Madam"
+      #   person.title_change # [ "Sir", "Madam" ]
+      #   person.title_changed? # true
+      #   person.title_was # "Sir"
+      #   person.reset_title!
+      def add_dirty_methods(name)
+        name = name.to_s
+        define_method("#{name}_change") { attribute_change(name) } unless instance_methods.include?("#{name}_change")
+        define_method("#{name}_changed?") { attribute_changed?(name) } unless instance_methods.include?("#{name}_changed?")
+        define_method("#{name}_was") { attribute_was(name) } unless instance_methods.include?("#{name}_was")
+        define_method("reset_#{name}!") { reset_attribute!(name) } unless instance_methods.include?("reset_#{name}!")
+      end
+    end
+  end
+end