timfel-active_cmis 0.3.1

data/LICENSE

@@ -0,0 +1,26 @@
+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.

data/README.md

@@ -0,0 +1,34 @@
+# ActiveCMIS Release 0.3.1 #
+**Homepage**:  <http://xaop.com/labs/activecmis>  
+**Git**:       <http://github.com/xaop/activecmis>  
+**Documentation**: <http://rdoc.info/github/xaop/activecmis/master/frames>
+**Author**:    XAOP bvba  
+**Copyright**: 2011
+**License**:   MIT License
+## Synopsis ##
+ActiveCMIS is Ruby library aimed at easing the interaction with various CMIS providers. It creates Ruby objects for CMIS objects, and creates Ruby classes that correspond to CMIS types.
+## Features ##
+- Read support for all CMIS object types
+- Write support and the ability to create new objects.
+- Support for paging
+
+## Changes since 0.2.6 ##
+The way authentication works has changed. If you previously used ActiveCMIS.connect then you're fine, otherwise the authentication changes will affect you: the authenticate methods on ActiveCMIS::Server and ActiveCMIS::Repository now return a new object, and don't change the authentication on the object itself. You can also specify optional authentication when connecting to a Server, or when calling the repository method.
+
+## Installation ##
+If you haven't installed Nokogiri yet it will be installed automatically, you will need a C compiler and the development files for libxml2.
+
+    > gem install active_cmis
+
+ActiveCMIS also depends on ntlm-http for ntlm authentication, unfortunately ntlm-http is broken on ruby 1.9.2
+## Usage ##
+    require 'active_cmis'
+    repository = ActiveCMIS.load_config('configuration', 'optional_filename_for_config')
+    f = repository.root_folder
+    p f.items.map do |i| i.cmis.name end
+
+And so on ...
+
+Full documentation of the API can be found at [rdoc.info](http://rdoc.info/projects/xaop/activecmis)
+
+A tutorial can be found at [the xaop site](http://xaop.com/labs/activecmis "tutorial")

data/Rakefile

@@ -0,0 +1,36 @@
+require 'rubygems'
+
+begin
+  require 'yard'
+
+  YARD::Rake::YardocTask.new do |t|
+    t.files   = ['lib/**/*.rb', '-', 'TODO']   # optional
+    t.options = ["--default-return", "::Object", "--query", "!@private", "--hide-void-return"]
+  end
+rescue LoadError
+  puts "Yard, or a dependency, not available. Install it with gem install yard"
+end
+
+begin
+  require 'jeweler'
+  require './lib/active_cmis/version'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "active_cmis"
+    gemspec.version = ActiveCMIS::Version::STRING
+    gemspec.summary = "A library to interact with CMIS repositories through the AtomPub/REST binding"
+    gemspec.description = "A CMIS library implementing both reading and updating capabilities through the AtomPub/REST binding to CMIS."
+    gemspec.email = "joeri@xaop.com"
+    gemspec.homepage = "http://xaop.com/labs/activecmis/"
+    gemspec.authors = ["Joeri Samson"]
+
+    gemspec.add_runtime_dependency 'nokogiri', '>= 1.4.1'
+    gemspec.add_runtime_dependency 'ntlm-http', '~> 0.1.1'
+    gemspec.add_runtime_dependency 'require_relative', '~> 1.0.2'
+
+    gemspec.required_ruby_version = '>= 1.8.6'
+    gemspec.files.exclude '.gitignore'
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end

data/TODO

@@ -0,0 +1,7 @@
+- For {ActiveCMIS::Rendition#get_file Rendition#get_file}:
+  * filename should be optional, a temporary file should be created (e.g. in /tmp) if no filename is given
+- For {ActiveCMIS::Type::ClassMethods#attributes Type::ClassMethods#attributes}: inherited parameter is misleading (+ default is wrong, some other code depends on it being true by default if it would work)
+- improve use of correct Exceptions:
+  * don't throw RuntimeError anymore (except perhaps where the library code is the only code that could cause the exception)
+  * try to use correct exceptions when receiving errors from server (may need some wrapper with repository specific code)
+- improve support for queries (i.e. allow interface such as the with_ATTR_NAME way of ActiveDCTM, allow select to return only a few attributes, ...)

data/active_cmis.gemspec

@@ -0,0 +1,77 @@
+# 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 = %q{timfel-active_cmis}
+  s.version = "0.3.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Joeri Samson"]
+  s.date = %q{2012-02-15}
+  s.description = %q{A CMIS library implementing both reading and updating capabilities through the AtomPub/REST binding to CMIS.}
+  s.email = %q{joeri@xaop.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+    "README.md",
+    "TODO"
+  ]
+  s.files = [
+    "LICENSE",
+    "README.md",
+    "Rakefile",
+    "TODO",
+    "active_cmis.gemspec",
+    "lib/active_cmis.rb",
+    "lib/active_cmis/acl.rb",
+    "lib/active_cmis/acl_entry.rb",
+    "lib/active_cmis/active_cmis.rb",
+    "lib/active_cmis/atomic_types.rb",
+    "lib/active_cmis/attribute_prefix.rb",
+    "lib/active_cmis/collection.rb",
+    "lib/active_cmis/document.rb",
+    "lib/active_cmis/exceptions.rb",
+    "lib/active_cmis/folder.rb",
+    "lib/active_cmis/internal/caching.rb",
+    "lib/active_cmis/internal/connection.rb",
+    "lib/active_cmis/internal/utils.rb",
+    "lib/active_cmis/ns.rb",
+    "lib/active_cmis/object.rb",
+    "lib/active_cmis/policy.rb",
+    "lib/active_cmis/property_definition.rb",
+    "lib/active_cmis/query_result.rb",
+    "lib/active_cmis/rel.rb",
+    "lib/active_cmis/relationship.rb",
+    "lib/active_cmis/rendition.rb",
+    "lib/active_cmis/repository.rb",
+    "lib/active_cmis/server.rb",
+    "lib/active_cmis/type.rb",
+    "lib/active_cmis/version.rb"
+  ]
+  s.homepage = %q{http://xaop.com/labs/activecmis/}
+  s.require_paths = ["lib"]
+  s.required_ruby_version = Gem::Requirement.new(">= 1.8.6")
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{A library to interact with CMIS repositories through the AtomPub/REST binding}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<nokogiri>, [">= 1.4.1"])
+      s.add_runtime_dependency(%q<ntlm-http>, ["~> 0.1.1"])
+      s.add_runtime_dependency(%q<require_relative>, ["~> 1.0.2"])
+    else
+      s.add_dependency(%q<nokogiri>, [">= 1.4.1"])
+      s.add_dependency(%q<ntlm-http>, ["~> 0.1.1"])
+      s.add_dependency(%q<require_relative>, ["~> 1.0.2"])
+    end
+  else
+    s.add_dependency(%q<nokogiri>, [">= 1.4.1"])
+    s.add_dependency(%q<ntlm-http>, ["~> 0.1.1"])
+    s.add_dependency(%q<require_relative>, ["~> 1.0.2"])
+  end
+end
+

data/lib/active_cmis/acl.rb

@@ -0,0 +1,181 @@
+module ActiveCMIS
+  # ACLs belong to a document and have no identity of their own
+  #
+  # = Updating:
+  # The effect on documents other than the one this ACL belongs to depends
+  # on the repository.
+  #
+
+  class Acl
+    include Internal::Caching
+
+    # @return [Object] The document or object from which we got this ACL
+    attr_reader :document
+    # @return [Repository]
+    attr_reader :repository
+
+    # @private
+    def initialize(repository, document, link, _data = nil)
+      @repository = repository
+      @document   = document
+      @self_link  = case link
+                    when URI; link
+                    else URI(link)
+                    end
+      @data = _data if _data
+    end
+
+    # Returns an array with all Acl entries.
+    # @return [Array<AclEntry>]
+    def permissions
+      data.xpath("c:permission", NS::COMBINED).map do |permit|
+        principal      = nil
+        permissions    = []
+        direct         = false
+        permit.children.each do |child|
+          next unless child.namespace && child.namespace.href == NS::CMIS_CORE
+
+          case child.name
+          when "principal"
+            child.children.map do |n|
+              next unless n.namespace && n.namespace.href == NS::CMIS_CORE
+
+              if n.name == "principalId" && principal.nil?
+                principal = convert_principal(n.text)
+              end
+            end
+          when "permission"
+            permissions << child.text
+          when "direct"
+            direct = AtomicType::Boolean.xml_to_bool(child.text)
+          end
+        end
+        AclEntry.new(principal, permissions, direct)
+      end
+    end
+    cache :permissions
+
+    # An indicator that the ACL fully describes the permissions for this object.
+    # This means that there are no other security constraints.
+    def exact?
+      @exact ||= begin
+                   value = data.xpath("c:exact", NS::COMBINED)
+                   if value.empty?
+                     false
+                   elsif value.length == 1
+                     AtomicType::Boolean.xml_to_bool(value.first.text)
+                   else
+                     raise "Unexpected multiplicity of exactness ACL"
+                   end
+                 end
+    end
+
+    # @param [String, :anonymous, :world] user Can be "cmis:user" to indicate the currently logged in user.
+    # For :anonymous and :world you can use both the the active_cmis symbol or the name used by the CMIS repository
+    # @param permissions (see ActiveCMIS::AclEntry#initialize)
+    # @return [void]
+    def grant_permission(user, *permissions)
+      principal = convert_principal(user)
+
+      relevant = self.permissions.select {|p| p.principal == principal && p.direct?}
+      if relevant = relevant.first
+        self.permissions.delete relevant
+        permissions.concat(relevant.permissions)
+      end
+
+      @updated = true
+      self.permissions << AclEntry.new(principal, permissions, true)
+    end
+
+    # @param (see ActiveCMIS::Acl#grant_permission)
+    # @return [void]
+    def revoke_permission(user, *permissions)
+      principal = convert_principal(user)
+
+      keep = self.permissions.reject {|p| p.principal == principal && p.permissions.any? {|t| permissions.include? t} }
+
+      relevant = self.permissions.select {|p| p.principal == principal && p.permissions.any? {|t| permissions.include? t} }
+      changed  = relevant.map {|p| AclEntry.new(principal, p.permissions - permissions, p.direct?) }
+
+      @updated = true
+      @permissions = keep + changed
+    end
+
+    # @param user (see ActiveCMIS::Acl#grant_permission)
+    # @return [void]
+    def revoke_all_permissions(user)
+      principal = convert_principal(user)
+      @updated = true
+      permissions.reject! {|p| p.principal == principal}
+    end
+
+    # Needed to actually execute changes on the server, this method is also executed when you save an object with a modified ACL
+    # @return [void]
+    def apply
+      body = Nokogiri::XML::Builder.new do |xml|
+        xml.acl("xmlns" => NS::CMIS_CORE) do
+          permissions.each do |permission|
+            xml.permission do
+              xml.principal { xml.principalId { convert_principal(permission.principal) }}
+              xml.direct    { permission.direct? }
+              permission.each do |permit|
+                xml.permission { permit }
+              end
+            end
+          end
+        end
+      end
+      conn.put(self_link("onlyBasicPermissions" => false), body)
+      reload
+    end
+
+    # True if there are local changes to the ACL
+    def updated?
+      @updated
+    end
+
+    # @return [void]
+    def reload
+      @updated = false
+      @exact = nil
+      __reload
+    end
+
+    private
+    def self_link(options = {})
+      Internal::Utils.append_parameters(@self_link, options)
+    end
+
+    def conn
+      repository.conn
+    end
+
+    def data
+      conn.get_xml(self_link).xpath("c:acl", NS::COMBINED)
+    end
+    cache :data
+
+    def anonymous_user
+      repository.anonymous_user
+    end
+    def world_user
+      repository.world_user
+    end
+
+    def convert_principal(principal)
+      case principal
+      when :anonymous
+        anonymous_user
+      when :world
+        world
+      when anonymous_user
+        :anonymous
+      when world_user
+        :world
+      else
+        principal
+      end
+    end
+
+  end
+end

data/lib/active_cmis/acl_entry.rb

@@ -0,0 +1,26 @@
+module ActiveCMIS
+  class AclEntry
+    # @param [<String>] permissions A list of permissions, valid values depend on the repository
+    # @private
+    def initialize(principal, permissions, direct)
+      @principal = principal.freeze
+      @permissions = permissions.freeze
+      @permissions.each {|p| p.freeze}
+      @direct = direct
+    end
+
+
+    # Normal users are represented with a string, a non-logged in user is known
+    # as :anonymous, the principal :world represents the group of all logged in
+    # users.
+    # @return [String, :world, :anonymous]
+    attr_reader :principal
+    # @return [<String>] A frozen array of strings with the permissions
+    attr_reader :permissions
+
+    # True if this is the direct representation of the ACL from the repositories point of view. This means there are no hidden differences that can't be expressed within the limitations of CMIS
+    def direct?
+      @direct
+    end
+  end
+end

data/lib/active_cmis/active_cmis.rb

@@ -0,0 +1,87 @@
+module ActiveCMIS
+  # Default logger: no output
+  # @return [Logger]
+  def self.default_logger
+    @default_logger ||= Logger.new(nil)
+  end
+
+  # server_url and repository_id are required options
+  #
+  # server_login, server_password and server_auth can be used to authenticate against the server,
+  # server_auth is optional and defaults to :basic
+  #
+  # You can also authenticate to the repository, by replacing server_ with repository_, by default
+  # the repository will use the same authentication parameters as the server
+  #
+  # The amoung of logging can be configured by setting log_level (default WARN), this can be done either
+  # by naming a Logger::Severity constant or the equivalent integer
+  #
+  # The destination of the logger output can be set with log_file (defaults to STDOUT), (should not contain ~)
+  #
+  # Default locations for the config file are: ./cmis.yml and .cmis.yml in that order
+  # @return [Repository]
+  def self.connect(config)
+    if config.is_a? Hash
+      if config.has_key? "log_file"
+        trace_file = config["log_file"]
+        if trace_file == "-"
+          trace_file = STDOUT
+        end
+        logger = Logger.new(trace_file)
+      else
+        logger = default_logger
+      end
+      if config.has_key? "log_level"
+        logger.level = (Logger.const_get(config["log_level"].upcase) rescue config["log_level"].to_i)
+      else
+        logger.level = Logger::WARN
+      end
+
+      if user_name = config["server_login"] and password = config["server_password"]
+        auth_type = config["server_auth"] || :basic
+        authentication_info = [auth_type, user_name, password]
+      end
+      server = Server.new(config["server_url"], logger, authentication_info)
+      if user_name = config["repository_login"] and password = config["repository_password"]
+        auth_type = config["repository_auth"] || :basic
+        authentication_info = [auth_type, user_name, password]
+      end
+      repository = server.repository(config["repository_id"], authentication_info)
+      return repository
+    else
+      raise "Configuration does not have correct format (#{config.class} is not a hash)"
+    end
+  end
+
+  # Will search for a given configuration in a file, and return the equivalent Repository
+  #
+  # The options that can be used are the same as for the connect method
+  #
+  # Default locations for the config file are: ./cmis.yml and .cmis.yml in that order
+  # @return [Repository]
+  def self.load_config(config_name, file = nil)
+    if file.nil?
+      ["cmis.yml", File.join(ENV["HOME"], ".cmis.yml")].each do |sl|
+        if File.exist?(sl)
+          file ||= sl
+        end
+      end
+      if file.nil?
+        raise "No configuration provided, and none found in standard locations"
+      end
+    elsif !File.exist?(file)
+      raise "Configuration file #{file} does not exist"
+    end
+
+    config = YAML.load_file(file)
+    if config.is_a? Hash
+      if config = config[config_name]
+        connect(config)
+      else 
+        raise "Configuration not found in file"
+      end
+    else
+      raise "Configuration file #{file} does not have right format (not a hash)"
+    end
+  end
+end