activesp 0.0.1 → 0.0.4

data/lib/activesp/permission_set.rb

@@ -1,3 +1,28 @@
+# Copyright (c) 2010 XAOP bvba
+# 
+# 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.
+
 module ActiveSP
   
   class PermissionSet
@@ -6,22 +31,32 @@ module ActiveSP
     
     attr_reader :scope
     
+    # @private
     def initialize(scope)
       @scope = scope
     end
     
-    def permissions
-      @scope.send(:permissions)
-    end
-    
+    # See {Base#key}
+    # @return [String]
     def key
       encode_key("P", [@scope.key])
     end
     
+    # Returns the permissions in this permission set as an array of hashes with :accessor mapping to a user,
+    # group or role and :mask mapping to the permission as an integer
+    # @return [Array<Hash{:accessor, :permission => User, Group, Role, Integer}>]
+    # @example
+    #   set.permissions #=> [{:accessor=>#<ActiveSP::User login_name=SHAREPOINT\system>, :mask=>134287360}]
+    def permissions
+      @scope.send(:permissions)
+    end
+    
+    # @private
     def to_s
       "#<ActiveSP::PermissionSet scope=#{@scope}>"
     end
     
+    # @private
     alias inspect to_s
     
   end

data/lib/activesp/persistent_caching.rb

@@ -1,7 +1,35 @@
+# Copyright (c) 2010 XAOP bvba
+# 
+# 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.
+
 module ActiveSP
   
+  # @private
   module PersistentCaching
     
+  private
+    
     def persistent(&blk)
       class << self ; self ; end.instance_eval do
         alias_method :old_new, :new
@@ -18,6 +46,7 @@ module ActiveSP
     
   end
   
+  # @private
   class PersistentCache
     
     def initialize
@@ -38,11 +67,42 @@ module ActiveSP
   
   module PersistentCachingConfig
     
+    # Configures the scope of the persistent cache. The default scope of the cache
+    # is the {Connection} object, i.e., each connection has its own cache. For example
+    # you can use this to make thread local caches. Note that the cache is not actually
+    # thread safe at this point so this may not be such a bad idea.
+    #
+    # Caching in ActiveSP at the moment is very aggressive. What this means that everything
+    # you ever accessed will be cached. You can override the cache for a particular object
+    # by calling {Base#reload} on it. One advantage of this caching strategy is that every time
+    # you access an object in SharePoint, it is guaranteed to be the same object in Ruby as
+    # well, irrespective of how you obtained a reference to that object. This eliminates a
+    # whole slew of issues, but you need to be aware of this.
+    #
+    # This method expects a block to which a new cache object is passed. The idea is that
+    # you store this cache object in a place that reflects the scope of your cache. If you
+    # already had a cache object stored for you current scope, you do not do anything with
+    # the cache object. The cache object that the block returns is the cache that will be used.
+    # Note that the block is called everytime ActiveSP needs the cache, so make it as
+    # efficient as possible. The example below illustrates how you can use the ||= operator
+    # for this to get a thread local cache.
+    #
+    # You can use this block to return a cache of your own. A cache is only expected to have
+    # a lookup method to which the cache key is passed (do not assume it is an integer or a
+    # string because it is not) as parameter and is expected to return the value for that
+    # key. In case of a cache miss, the method should yield to retrieve the value, store it
+    # with the given key and return the value. You can use this to plug in a cache that has
+    # a limited size, or that uses weak references to clean up the cache. The latter suggestion
+    # is a lot safer than the former!
+    #
+    # @example How to configure caching strategy
+    #   c = ActiveSP::Connection.new(:login => l, :password => p, :root => r)
+    #   c.configure_persistent_cache { |cache| Thread.current[:sp_cache] ||= cache }
     def configure_persistent_cache(&blk)
       @last_persistent_cache_object = PersistentCache.new
       class << self ; self ; end.send(:define_method, :persistent_cache) do
         cache = blk.call(@last_persistent_cache_object)
-        @last_persistent_cache_object = PersistentCache.new unless cache == @last_persistent_cache_object
+        @last_persistent_cache_object = PersistentCache.new if cache == @last_persistent_cache_object
         cache
       end
     end

data/lib/activesp/role.rb

@@ -1,3 +1,28 @@
+# Copyright (c) 2010 XAOP bvba
+# 
+# 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.
+
 module ActiveSP
   
   class Role < Base
@@ -7,43 +32,59 @@ module ActiveSP
     include Util
     include InSite
     
-    attr_reader :name
-    
     persistent { |site, name, *a| [site.connection, [:role, name]] }
+    # @private
     def initialize(site, name)
       @site, @name = site, name
     end
     
+    # See {Base#key}
+    # @return [String]
     def key
       encode_key("R", [@name])
     end
     
+    # Returns the list of users in this role
+    # @return [User]
     def users
       call("UserGroup", "get_user_collection_from_role", "roleName" => @name).xpath("//spdir:User", NS).map do |row|
         attributes = clean_attributes(row.attributes)
         User.new(@site, attributes["LoginName"])
       end
     end
-    cache :users, :dup => true
+    cache :users, :dup => :always
     
+    # Returns the list of groups in this role
+    # @return [Group]
     def groups
       call("UserGroup", "get_group_collection_from_role", "roleName" => @name).xpath("//spdir:Group", NS).map do |row|
         attributes = clean_attributes(row.attributes)
         Group.new(@site, attributes["Name"])
       end
     end
-    cache :groups, :dup => true
+    cache :groups, :dup => :always
+    
+    # Returns true. The same method is present on {Group} where it returns false. Roles and groups can generally be
+    # duck-typed, and this method is there for the rare case where you do need to make the distinction
+    # @return [Boolean]
+    def is_role?
+      true
+    end
     
+    # See {Base#save}
+    # @return [void]
+    def save
+      p untype_cast_attributes(@site, nil, internal_attribute_types, changed_attributes)
+    end
+    
+    # @private
     def to_s
       "#<ActiveSP::Role name=#{@name}>"
     end
     
+    # @private
     alias inspect to_s
     
-    def is_role?
-      true
-    end
-    
   private
     
     def data

data/lib/activesp/root.rb

@@ -1,5 +1,31 @@
+# Copyright (c) 2010 XAOP bvba
+# 
+# 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.
+
 module ActiveSP
   
+  # @private
   NS = {
     "sp" => "http://schemas.microsoft.com/sharepoint/soap/",
     "z" => "#RowsetSchema",
@@ -10,34 +36,71 @@ module ActiveSP
     
     extend Caching
     
+    # Returns the root site as an object of class {Site}
+    # @return [Site]
     def root
       Site.new(self, @root_url)
     end
     cache :root
     
+    # Returns the list of users in the system
+    # @return [Array<User>]
     def users
       root.send(:call, "UserGroup", "get_user_collection_from_site").xpath("//spdir:User", NS).map do |row|
         attributes = clean_attributes(row.attributes)
         User.new(root, attributes["LoginName"])
       end
     end
-    cache :users, :dup => true
+    cache :users, :dup => :always
     
+    # Returns the user with the given login, or nil when the user does not exist
+    # @param [String] login The login of the user
+    # @return [User, nil]
+    def user(login)
+      if user = users_by_login[login]
+        user
+      elsif data = root.send(:call, "UserGroup", "get_user_info", "userLoginName" => login).xpath("//spdir:User", NS).first
+        users_by_login[login] = User.new(root, login, clean_attributes(data))
+      end
+    end
+    
+    # Returns the list of groups in the system
+    # @return [Array<Group>]
     def groups
       root.send(:call, "UserGroup", "get_group_collection_from_site").xpath("//spdir:Group", NS).map do |row|
         attributes = clean_attributes(row.attributes)
         Group.new(root, attributes["Name"])
       end
     end
-    cache :groups, :dup => true
+    cache :groups, :dup => :always
+    
+    def group(name)
+      if group = groups_by_name[name]
+        group
+      end
+    end
     
+    # Returns the list of roles in the system
+    # @return [Array<Role>]
     def roles
       root.send(:call, "UserGroup", "get_role_collection_from_web").xpath("//spdir:Role", NS).map do |row|
         attributes = clean_attributes(row.attributes)
         Role.new(root, attributes["Name"])
       end
     end
-    cache :roles, :dup => true
+    cache :roles, :dup => :always
+    
+  private
+    
+    def users_by_login
+      users.inject({}) { |h, u| h[u.login_name] = u ; h }
+    end
+    cache :users_by_login
+    
+    def groups_by_name
+      groups.inject({}) { |h, g| h[g.Name] = g ; h }
+    end
+    cache :groups_by_name
     
   end
   
@@ -47,6 +110,7 @@ module ActiveSP
     
   end
   
+  # @private
   module InSite
     
   private

data/lib/activesp/site.rb

@@ -1,3 +1,28 @@
+# Copyright (c) 2010 XAOP bvba
+# 
+# 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.
+
 module ActiveSP
   
   class Site < Base
@@ -6,51 +31,73 @@ module ActiveSP
     extend PersistentCaching
     include Util
     
-    attr_reader :url, :connection
+    # The URL of this site
+    # @return [String]
+    attr_reader :url
+    # @private
+    attr_reader :connection
     
     persistent { |connection, url, *a| [connection, [:site, url]] }
+    # @private
     def initialize(connection, url, depth = 0)
       @connection, @url, @depth = connection, url, depth
       @services = {}
     end
     
+    # @private
     def relative_url(url = @url)
       url[@connection.root_url.rindex("/") + 1..-1]
     end
     
+    # Returns the containing site, or nil if this is the root site
+    # @return [Site]
     def supersite
-      if @depth > 0
-        Site.new(@connection, File.dirname(@url), @depth - 1)
+      unless is_root_site?
+        Site.new(@connection, ::File.dirname(@url), @depth - 1)
       end
     end
     cache :supersite
     
+    # Returns the root site, or this site if it is the root site
+    # @return [Site]
     def rootsite
-      @depth > 0 ? supersite.rootsite : self
+      is_root_site? ? self : supersite.rootsite
     end
     cache :rootsite
     
+    # Returns true if this site is the root site
+    # @return [Boolean]
     def is_root_site?
       @depth == 0
     end
     
-    def key
+    # See {Base#key}
+    # @return [String]
+    def key # This documentation is not ideal. The ideal doesn't work out of the box
       encode_key("S", [@url[@connection.root_url.length + 1..-1], @depth])
     end
     
+    # Returns the list of sites below this site. Does not recurse
+    # @return [Array<List>]
     def sites
       result = call("Webs", "get_web_collection")
       result.xpath("//sp:Web", NS).map { |web| Site.new(connection, web["Url"].to_s, @depth + 1) }
     end
-    cache :sites, :dup => true
+    cache :sites, :dup => :always
     
+    # Returns the site with the given name. This name is what appears in the URL as name and is immutable. Return nil
+    # if such a site does not exist
+    # @param [String] name The name if the site
+    # @return [Site]
     def site(name)
-      result = call("Webs", "get_web", "webUrl" => File.join(@url, name))
+      result = call("Webs", "get_web", "webUrl" => ::File.join(@url, name))
       Site.new(connection, result.xpath("//sp:Web", NS).first["Url"].to_s, @depth + 1)
     rescue Savon::SOAPFault
       nil
     end
     
+    # Returns the list if lists in this sute. Does not recurse
+    # @return [Array<List>]
     def lists
       result1 = call("Lists", "get_list_collection")
       result2 = call("SiteData", "get_list_collection")
@@ -66,28 +113,42 @@ module ActiveSP
         List.new(self, list["ID"].to_s, list["Title"].to_s, clean_attributes(list.attributes), result2_by_id[list["ID"].to_s])
       end
     end
-    cache :lists, :dup => true
+    cache :lists, :dup => :always
     
+    # Returns the list with the given name. The name is what appears in the URL as name and is immutable. Returns nil
+    # if such a list does not exist
+    # @param [String] name The name of the list
+    # @return [List]
     def list(name)
-      lists.find { |list| File.basename(list.attributes["RootFolder"]) == name }
+      lists.find { |list| ::File.basename(list.url) == name }
     end
     
+    # Returns the site or list with the given name, or nil if it does not exist
+    # @param [String] name The name of the site or list
+    # @return [Site, List]
     def /(name)
       list(name) || site(name)
     end
     
+    # Returns the list of content types defined for this site. These include the content types defined on
+    # containing sites as they are automatically inherited
+    # @return [Array<ContentType>]
     def content_types
       result = call("Webs", "get_content_types", "listName" => @id)
       result.xpath("//sp:ContentType", NS).map do |content_type|
         supersite && supersite.content_type(content_type["ID"]) || ContentType.new(self, nil, content_type["ID"], content_type["Name"], content_type["Description"], content_type["Version"], content_type["Group"])
       end
     end
-    cache :content_types, :dup => true
+    cache :content_types, :dup => :always
     
+    # @private
     def content_type(id)
       content_types.find { |t| t.id == id }
     end
     
+    # Returns the permission set associated with this site. This returns the permission set of
+    # the containing site if it does not have a permission set of its own
+    # @return [PermissionSet]
     def permission_set
       if attributes["InheritedSecurity"]
         supersite.permission_set
@@ -97,27 +158,47 @@ module ActiveSP
     end
     cache :permission_set
     
+    # Returns the list of fields for this site. This includes fields inherited from containing sites
+    # @return [Array<Field>]
     def fields
       call("Webs", "get_columns").xpath("//sp:Field", NS).map do |field|
         attributes = clean_attributes(field.attributes)
         supersite && supersite.field(attributes["ID"].downcase) || Field.new(self, attributes["ID"].downcase, attributes["StaticName"], attributes["Type"], nil, attributes) if attributes["ID"] && attributes["StaticName"]
       end.compact
     end
-    cache :fields, :dup => true
+    cache :fields, :dup => :always
     
+    # Returns the result of {Site#fields} hashed by name
+    # @return [Hash{String => Field}]
     def fields_by_name
       fields.inject({}) { |h, f| h[f.attributes["StaticName"]] = f ; h }
     end
-    cache :fields_by_name, :dup => true
+    cache :fields_by_name, :dup => :always
     
+    # @private
     def field(id)
       fields.find { |f| f.ID == id }
     end
     
+    # See {Base#save}
+    # @return [void]
+    def save
+      p untype_cast_attributes(self, nil, internal_attribute_types, changed_attributes)
+    end
+    
+    def accessible?
+      data
+      true
+    rescue Savon::HTTPError
+      false
+    end
+    
+    # @private
     def to_s
       "#<ActiveSP::Site url=#{@url}>"
     end
     
+    # @private
     alias inspect to_s
     
   private
@@ -136,17 +217,25 @@ module ActiveSP
     end
     
     def data
+      # Looks like you can't call this as a non-admin. To investigate further
       call("SiteData", "get_web")
+    rescue Savon::HTTPError
+      # This can fail when you don't have access to this site
+      call("Webs", "get_web", "webUrl" => ".")
     end
     cache :data
     
     def attributes_before_type_cast
-      element = data.xpath("//sp:sWebMetadata", NS).first
-      result = {}
-      element.children.each do |ch|
-        result[ch.name] = ch.inner_text
+      if element = data.xpath("//sp:sWebMetadata", NS).first
+        result = {}
+        element.children.each do |ch|
+          result[ch.name] = ch.inner_text
+        end
+        result
+      else
+        element = data.xpath("//sp:Web", NS).first
+        clean_attributes(element.attributes)
       end
-      result
     end
     cache :attributes_before_type_cast
     
@@ -176,19 +265,20 @@ module ActiveSP
     end
     
     def permissions
-      result = call("Permissions", "get_permission_collection", "objectName" => File.basename(@url), "objectType" => "Web")
+      result = call("Permissions", "get_permission_collection", "objectName" => ::File.basename(@url), "objectType" => "Web")
       result.xpath("//spdir:Permission", NS).map do |row|
         accessor = row["MemberIsUser"][/true/i] ? User.new(rootsite, row["UserLogin"]) : Group.new(rootsite, row["GroupName"])
         { :mask => Integer(row["Mask"]), :accessor => accessor }
       end
     end
-    cache :permissions, :dup => true
+    cache :permissions, :dup => :always
     
+    # @private
     class Service
       
       def initialize(site, name)
         @site, @name = site, name
-        @client = Savon::Client.new(File.join(site.url, "_vti_bin", name + ".asmx?WSDL"))
+        @client = Savon::Client.new(::File.join(URI.escape(site.url), "_vti_bin", name + ".asmx?WSDL"))
         @client.request.ntlm_auth(site.connection.login, site.connection.password) if site.connection.login
       end