active_cmis 0.1.0

data/.gitignore

@@ -0,0 +1,3 @@
+doc
+.yardoc
+pkg

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,30 @@
+# ActiveCMIS Release 0.1.0 #
+**Homepage**:  <http://xaop.com/labs/activecmis>   
+**Git**:       <http://github.com/xaop/activecmis>   
+**Author**:    XAOP bvba   
+**Copyright**: 2010
+**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
+
+## 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.
+
+If you don't have Yardoc or bluecloth installed you won't be able to build the documentation and will need to add `--no-rdoc --no-ri` to the next command (or install yard and bluecloth first).
+
+    > gem install active_cmis
+## 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 <http://xaop.com/labs/activecmis/doc/index.html>
+
+A tutorial can be found at [the xaop site](http://xaop.com/labs/activecmis "tutorial")

data/Rakefile

@@ -0,0 +1,36 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+
+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 jeweler"
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "active_cmis"
+    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.has_rdoc = 'yard'
+    gemspec.extra_rdoc_files = ['TODO']
+    gemspec.rdoc_options << "--default-return" << "::Object" << "--query" << "!@private" << "--hide-void-return"
+
+    gemspec.required_ruby_version = '>= 1.8.6'
+  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,8 @@
+- 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
+  * Downloading content should use streaming where possible
+- 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/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/active_cmis.rb

@@ -0,0 +1,27 @@
+require 'nokogiri'
+require 'net/http'
+require 'net/https'
+require 'yaml'
+require 'logger'
+require 'active_cmis/internal/caching'
+require 'active_cmis/internal/connection'
+require 'active_cmis/exceptions'
+require 'active_cmis/server'
+require 'active_cmis/repository'
+require 'active_cmis/object'
+require 'active_cmis/document'
+require 'active_cmis/folder'
+require 'active_cmis/policy'
+require 'active_cmis/relationship'
+require 'active_cmis/type'
+require 'active_cmis/atomic_types'
+require 'active_cmis/property_definition'
+require 'active_cmis/collection.rb'
+require 'active_cmis/rendition.rb'
+require 'active_cmis/acl.rb'
+require 'active_cmis/acl_entry.rb'
+require 'active_cmis/ns'
+require 'active_cmis/active_cmis'
+require 'active_cmis/internal/utils'
+require 'active_cmis/rel'
+require 'active_cmis/attribute_prefix'

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.add_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,74 @@
+module ActiveCMIS
+  # Default logger: Outputs to STDOUT and has level set to DEBUG
+  # @return [Logger]
+  def self.default_logger
+    @default_logger ||= Logger.new(STDOUT)
+  end
+
+  # Will search for a given configuration in a file, and return the equivalent Repository
+  #
+  # 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.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
+      config = config[config_name]
+      if config.is_a? Hash
+        if config.has_key? "log_file"
+          logger = Logger.new(config["trace_file"])
+        else
+          logger = default_logger
+        end
+        if config.has_key? "log_level"
+          logger.level = Logger.const_get(config["trace_level"].upcase) rescue config["trace_level"].to_i
+        else
+          logger.level = Logger::WARN
+        end
+
+        server = Server.new(config["server_url"], logger)
+        if user_name = config["server_login"] and password = config["server_password"]
+          auth_type = config["server_auth"] || :basic
+          server.authenticate(auth_type, user_name, password)
+        end
+        repository = server.repository(config["repository_id"])
+        if user_name = config["repository_login"] and password = config["repository_password"]
+          auth_type = config["repository_auth"] || :basic
+          repository.authenticate(auth_type, user_name, password)
+        end
+        return repository
+      elsif config.nil?
+        raise "Configuration not found in file"
+      else
+        raise "Configuration does not have right format (not a hash)"
+      end
+    else
+      raise "Configuration file does not have right format (not a hash)"
+    end
+  end
+end

data/lib/active_cmis/atomic_types.rb

@@ -0,0 +1,232 @@
+module ActiveCMIS
+  module AtomicType
+    class CommonBase
+      def cmis2rb(value)
+        if value.children.empty? && value.attribute("nil")
+          nil
+        else
+          _cmis2rb(value)
+        end
+      end
+      def rb2cmis(xml, value)
+        if value.nil?
+          xml.value("xmlns:xsi" => "http://www.w3.org/2001/XMLSchema-instance", "xsi:nil" => "true")
+        else
+          _rb2cmis(xml, value)
+        end
+      end
+      def can_handle?(value)
+        raise NotImplementedError
+      end
+    end
+
+    class String < CommonBase
+      attr_reader :max_length
+      def initialize(max_length)
+        @max_length = max_length
+      end
+
+      def to_s
+        "String"
+      end
+
+      def _cmis2rb(value)
+        value.text
+      end
+      def _rb2cmis(xml, value)
+        v = value.to_s
+        if max_length && v.length > max_length
+          raise Error::InvalidArgument.new("String representation is longer than maximum (max: #{max_length}, string: \n'\n#{v}\n')\n")
+        end
+        xml["c"].value v
+      end
+      def can_handle?(value)
+        value.respond_to?(:to_s)
+      end
+
+      private :_cmis2rb, :_rb2cmis
+    end
+
+    # Precision is ignored?
+    class Decimal < CommonBase
+      attr_reader :precision, :min_value, :max_value
+      def initialize(precision, min_value, max_value)
+        @precision, @min_value, @max_value = precision, min_value, max_value
+      end
+
+      def to_s
+        "Decimal"
+      end
+
+      def _cmis2rb(value)
+        value.text.to_f
+      end
+      def _rb2cmis(xml, value)
+        v = value.to_f
+        if (min_value && v < min_value) || (max_value && v > max_value)
+          raise Error::InvalidArgument.new("OutOfBounds: #{v} should be between #{min_value} and #{max_value}")
+        end
+        xml["c"].value("%f" % v)
+      end
+      def can_handle?(value)
+        value.respond_to?(:to_s)
+      end
+
+      private :_cmis2rb, :_rb2cmis
+    end
+
+    class Integer < CommonBase
+      attr_reader :min_value, :max_value
+      def initialize(min_value, max_value)
+        @min_value, @max_value = min_value, max_value
+      end
+
+      def to_s
+        "Integer"
+      end
+
+      def _cmis2rb(value)
+        value.text.to_i
+      end
+      def _rb2cmis(xml, value)
+        v = value.to_int
+        if (min_value && v < min_value) || (max_value && v > max_value)
+          raise Error::InvalidArgument.new("OutOfBounds: #{v} should be between #{min_value} and #{max_value}")
+        end
+        xml["c"].value("%i" % v)
+      end
+      def can_handle?(value)
+        value.respond_to?(:to_int)
+      end
+
+      private :_cmis2rb, :_rb2cmis
+    end
+
+    class DateTime < CommonBase
+      attr_reader :resolution
+
+      @instances ||= {}
+      def self.new(precision)
+        raise ArgumentError.new("Got precision = #{precision.inspect}") unless [YEAR, DATE, TIME].include? precision.to_s.downcase
+        @instances[precision] ||= super
+      end
+
+      def to_s
+        "DateTime"
+      end
+
+      def initialize(resolution)
+        @resolution = resolution
+      end
+      YEAR = "year"
+      DATE = "date"
+      TIME = "time"
+
+      def _cmis2rb(value)
+        case @resolution
+        when YEAR, DATE; ::DateTime.parse(value.text).to_date
+        when TIME; ::DateTime.parse(value.text)
+        end
+      end
+      def _rb2cmis(xml, value)
+        # FIXME: respect resolution, I still have to find out how to do that
+        xml["c"].value(value.strftime("%Y-%m-%dT%H:%M:%S%Z"))
+      end
+      def can_handle?(value)
+        value.respond_to?(:strftime)
+      end
+
+      private :_cmis2rb, :_rb2cmis
+    end
+
+    class Singleton < CommonBase
+      def self.new
+        @singleton ||= super
+      end
+    end
+
+    class Boolean < Singleton
+      def self.xml_to_bool(value)
+        case value
+        when "true", "1"; true
+        when "false", "0"; false
+        else raise ActiveCMIS::Error.new("An invalid boolean was found in CMIS")
+        end
+      end
+
+      def to_s
+        "Boolean"
+      end
+
+      def _cmis2rb(value)
+        self.class.xml_to_bool(value.text)
+      end
+      def _rb2cmis(xml, value)
+        xml["c"].value( (!!value).to_s )
+      end
+      def can_handle?(value)
+        [true, false].include?(value)
+      end
+
+      private :_cmis2rb, :_rb2cmis
+    end
+
+    class URI < Singleton
+      def to_s
+        "Uri"
+      end
+
+      def _cmis2rb(value)
+        URI.parse(value.text)
+      end
+      def _rb2cmis(xml, value)
+        xml["c"].value( value.to_s )
+      end
+      def can_handle?(value)
+        value.respond_to?(:to_s)
+      end
+
+      private :_cmis2rb, :_rb2cmis
+    end
+
+    class ID < Singleton
+      def to_s
+        "Id"
+      end
+
+      def _cmis2rb(value)
+        value.text
+      end
+      def _rb2cmis(xml, value)
+        case value
+        when ::ActiveCMIS::Object; value.id
+        else xml["c"].value( value.to_s )
+        end
+      end
+      def can_handle?(value)
+        value.class < ::ActiveCMIS::Object || value.respond_to?(:to_s)
+      end
+
+      private :_cmis2rb, :_rb2cmis
+    end
+
+    class HTML < Singleton
+      def to_s
+        "Html"
+      end
+
+      def _cmis2rb(value)
+        value.children
+      end
+      def _rb2cmis(xml, value)
+        # FIXME: Test that this works
+        xml["c"].value value
+      end
+      def can_handle?(value)
+        true # FIXME: this is probably incorrect
+      end
+
+      private :_cmis2rb, :_rb2cmis
+    end
+  end
+end