occi-api 4.2.0.beta.2 → 4.2.0.beta.3

data/lib/occi/api/client/client_base.rb

@@ -5,13 +5,8 @@ module Occi
       class ClientBase
 
         # a few attributes which should be visible outside the client
-        attr_reader :endpoint
-        attr_reader :auth_options
-        attr_reader :media_type
-        attr_reader :connected
-        attr_reader :model
-        attr_reader :logger
-        attr_reader :last_response
+        attr_reader :endpoint, :auth_options, :media_type
+        attr_reader :connected, :model, :logger, :last_response
         attr_reader :options
 
         def initialize(options = {})
@@ -23,17 +18,17 @@ module Occi
             :media_type => nil
           }
 
-          options = options.marshal_dump if options.is_a? OpenStruct
-          @options = defaults.merge options
+          options = options.marshal_dump if options.is_a?(OpenStruct)
+          @options = defaults.merge(options)
 
           # set Occi::Log
-          set_logger @options[:log]
+          @logger = get_logger(@options[:log])
 
           # check the validity and canonize the endpoint URI
-          set_endpoint @options[:endpoint]
+          @endpoint = get_endpoint_uri(@options[:endpoint])
 
           # pass auth options
-          set_auth @options[:auth]
+          @auth_options = get_auth(@options[:auth])
 
           # verify authN before attempting actual
           # message exchange with the server; this
@@ -42,7 +37,7 @@ module Occi
           preauthenticate
 
           # set accepted media types
-          set_media_type @options[:media_type]
+          @media_type = get_media_type(@options[:media_type])
 
           @connected = false
         end
@@ -82,7 +77,9 @@ module Occi
         #
         # @param [String] resource type identifier or just type name
         # @return [Array<String>] list of links
-        def list(resource_type_identifier=nil); end
+        def list(resource_type_identifier=nil)
+          raise Occi::Api::Client::Errors::NotImplementedError, "#{__method__} is just a stub!"
+        end
 
         # Retrieves descriptions for available resources specified by a type
         # identifier or resource location. If no type identifier or location
@@ -101,7 +98,9 @@ module Occi
         #
         # @param [String] resource type identifier, type name or resource location
         # @return [Occi::Core::Resources] list of resource descriptions
-        def describe(resource_type_identifier=nil); end
+        def describe(resource_type_identifier=nil)
+          raise Occi::Api::Client::Errors::NotImplementedError, "#{__method__} is just a stub!"
+        end
 
         # Creates a new resource on the server. Resource must be provided
         # as an instance of Occi::Core::Entity, e.g. instantiated using
@@ -118,7 +117,9 @@ module Occi
         #
         # @param [Occi::Core::Entity] resource to be created on the server
         # @return [String] URI of the new resource
-        def create(entity); end
+        def create(entity)
+          raise Occi::Api::Client::Errors::NotImplementedError, "#{__method__} is just a stub!"
+        end
 
         # Deploys a compute resource based on an OVF/OVA descriptor available
         # on a local file system.
@@ -128,7 +129,9 @@ module Occi
         #
         # @param [String] location of an OVF/OVA file
         # @return [String] URI of the new resource
-        def deploy(location); end
+        def deploy(location)
+          raise Occi::Api::Client::Errors::NotImplementedError, "#{__method__} is just a stub!"
+        end
 
         # Deploys a compute resource based on an OVF descriptor available
         # directly as a String.
@@ -138,7 +141,9 @@ module Occi
         #
         # @param [String] OVF descriptor (e.g., already read from a file or generated)
         # @return [String] URI of the new resource
-        def deploy_ovf(descriptor); end
+        def deploy_ovf(descriptor)
+          raise Occi::Api::Client::Errors::NotImplementedError, "#{__method__} is just a stub!"
+        end
 
         # Deploys a compute resource based on an OVA descriptor available
         # directly as a String.
@@ -148,7 +153,9 @@ module Occi
         #
         # @param [String] OVA descriptor (e.g., already read from a file or generated)
         # @return [String] URI of the new resource
-        def deploy_ova(descriptor); end
+        def deploy_ova(descriptor)
+          raise Occi::Api::Client::Errors::NotImplementedError, "#{__method__} is just a stub!"
+        end
 
         # Deletes a resource or all resource of a certain resource type
         # from the server.
@@ -160,17 +167,21 @@ module Occi
         #
         # @param [String] resource type identifier, type name or location
         # @return [Boolean] status
-        def delete(resource_type_identifier); end
+        def delete(resource_type_identifier)
+          raise Occi::Api::Client::Errors::NotImplementedError, "#{__method__} is just a stub!"
+        end
 
         # Triggers given action on a specific resource.
         #
         # @example
         #    TODO: add examples
         #
-        # @param [String] resource location
-        # @param [String] type of action
+        # @param [String] resource type or type identifier
+        # @param [Occi::Core::ActionInstance] type of action
         # @return [String] resource location
-        def trigger(resource_type_identifier, action); end
+        def trigger(resource_type_identifier, action_instance)
+          raise Occi::Api::Client::Errors::NotImplementedError, "#{__method__} is just a stub!"
+        end
 
         # Refreshes the Occi::Model used inside the client. Useful for
         # updating the model without creating a new instance or
@@ -178,7 +189,9 @@ module Occi
         #
         # @example
         #    client.refresh
-        def refresh; end
+        def refresh
+          raise Occi::Api::Client::Errors::NotImplementedError, "#{__method__} is just a stub!"
+        end
 
         ##############################################################################
         ######## STUBS END
@@ -196,36 +209,121 @@ module Occi
         # @param [String] resource name or resource identifier
         # @return [Occi::Core::Resource] new resource instance
         def get_resource(resource_type)
-          Occi::Log.debug("Instantiating #{resource_type} ...")
-
-          type_id = if @model.get_by_id resource_type
-            # we got a resource type identifier
-            resource_type
-          else
-            # we got a resource type name
-            type_ids = @model.kinds.to_a.select { |kind| kind.term == resource_type }
-            type_ids.first.type_identifier if type_ids.any?
-          end
+          Occi::Log.debug("Instantiating #{resource_type.inspect}")
 
+          type_id = get_resource_type_identifier(resource_type)
           raise "Unknown resource type! #{resource_type.inspect}" unless type_id
 
-          Occi::Core::Resource.new type_id
+          new_resource = Occi::Core::Resource.new(type_id)
+          new_resource.model = @model
+
+          new_resource
         end
 
-        # Retrieves all entity type identifiers related to a given type identifier
+        # Retrieves all available category types.
         #
         # @example
-        #    client.get_entity_type_identifiers_related_to 'network'
+        #    client.get_category_types # => [ "entity", "resource", "link" ]
+        #
+        # @return [Array<String>] list of available category types in a human-readable format
+        def get_category_types
+          @model.categories.to_a.collect { |category| category.term }
+        end
+
+        # Retrieves all available category type identifiers.
+        #
+        # @example
+        #    client.get_category_type_identifiers
+        #    # => [ "http://schemas.ogf.org/occi/core#entity",
+        #    #      "http://schemas.ogf.org/occi/core#resource",
+        #    #      "http://schemas.ogf.org/occi/core#link" ]
+        #
+        # @return [Array<String>] list of available category type identifiers
+        def get_category_type_identifiers
+          @model.categories.to_a.collect { |category| category.type_identifier }
+        end
+
+        # Retrieves available category type identifier for the given category type.
+        #
+        # @example
+        #    client.get_category_type_identifier("compute")
+        #     # => 'http://schemas.ogf.org/occi/infrastructure#compute'
+        #
+        # @return [String, nil] category type identifier for the given category type
+        def get_category_type_identifier(type)
+          return type if (type =~ URI::ABS_URI) || (type && type.start_with?('/'))
+
+          cats = @model.categories.to_a.select { |k| k.term == type }
+          tis = cats.collect { |c| c.type_identifier }
+          tis.uniq!
+
+          if tis.length > 1
+            raise Occi::Api::Client::Errors::AmbiguousNameError,
+                  "Category type #{type.inspect} is ambiguous, use a type identifier!"
+          end
+
+          tis.first
+        end
+
+        # Retrieves all kind type identifiers related to a given type identifier
+        #
+        # @example
+        #    client.get_kind_type_identifiers_related_to 'http://schemas.ogf.org/occi/infrastructure#network'
         #    # => [ "http://schemas.ogf.org/occi/infrastructure#network",
         #    #      "http://schemas.ogf.org/occi/infrastructure#ipnetwork" ]
         #
-        # @param [String] type_identifier
-        # @return [Array<String>] list of available entity type identifiers related to
-        #                         given type identifier in a human-readable format
-        def get_entity_types_related_to(type_identifier)
-          Occi::Log.debug("Getting entity type identifiers related to #{type_identifier}")
-          collection = @model.get type_identifier
-          collection.kinds.collect { |kind| kind.type_identifier }
+        # @param [String] type identifier
+        # @return [Array<String>] list of available kind type identifiers related to
+        #                         the given type identifier
+        def get_kind_type_identifiers_related_to(type_identifier)
+          Occi::Log.debug("Getting kind type identifiers related to #{type_identifier.inspect}")
+          collection = @model.get(type_identifier)
+          collection.kinds.to_a.collect { |kind| kind.type_identifier }
+        end
+
+        # Retrieves all available kind types.
+        #
+        # @example
+        #    client.get_kind_types # => [ "entity", "resource", "link" ]
+        #
+        # @return [Array<String>] list of available kind types in a human-readable format
+        def get_kind_types
+          @model.kinds.to_a.collect { |kind| kind.term }
+        end
+
+        # Retrieves all available kind type identifiers.
+        #
+        # @example
+        #    client.get_kind_type_identifiers
+        #    # => [ "http://schemas.ogf.org/occi/core#entity",
+        #    #      "http://schemas.ogf.org/occi/core#resource",
+        #    #      "http://schemas.ogf.org/occi/core#link" ]
+        #
+        # @return [Array<String>] list of available kind type identifiers
+        def get_kind_type_identifiers
+          @model.kinds.to_a.collect { |kind| kind.type_identifier }
+        end
+
+        # Retrieves available kind type identifier for the given kind type.
+        #
+        # @example
+        #    client.get_kind_type_identifier("compute")
+        #     # => 'http://schemas.ogf.org/occi/infrastructure#compute'
+        #
+        # @return [String, nil] kind type identifier for the given kind type
+        def get_kind_type_identifier(type)
+          return type if (type =~ URI::ABS_URI) || (type && type.start_with?('/'))
+
+          kinds = @model.kinds.to_a.select { |k| k.term == type }
+          tis = kinds.collect { |k| k.type_identifier }
+          tis.uniq!
+
+          if tis.length > 1
+            raise Occi::Api::Client::Errors::AmbiguousNameError,
+                  "Kind type #{type.inspect} is ambiguous, use a type identifier!"
+          end
+
+          tis.first
         end
 
         # Retrieves all available entity types.
@@ -235,21 +333,44 @@ module Occi
         #
         # @return [Array<String>] list of available entity types in a human-readable format
         def get_entity_types
-          Occi::Log.debug("Getting entity types ...")
-          @model.kinds.to_a.collect { |kind| kind.term }
+          collection = @model.get(Occi::Core::Entity.kind.type_identifier)
+          collection.kinds.to_a.collect { |kind| kind.term }
         end
 
         # Retrieves all available entity type identifiers.
         #
         # @example
-        #    client.get_entity_type_identifiers
+        #    client.get_kind_type_identifiers
         #    # => [ "http://schemas.ogf.org/occi/core#entity",
         #    #      "http://schemas.ogf.org/occi/core#resource",
         #    #      "http://schemas.ogf.org/occi/core#link" ]
         #
         # @return [Array<String>] list of available entity types in a OCCI ID format
         def get_entity_type_identifiers
-          get_entity_types_related_to Occi::Core::Entity.kind.type_identifier
+          get_kind_type_identifiers_related_to Occi::Core::Entity.kind.type_identifier
+        end
+
+        # Retrieves available entity type identifier for the given entity type.
+        #
+        # @example
+        #    client.get_entity_type_identifier("compute")
+        #     # => 'http://schemas.ogf.org/occi/infrastructure#compute'
+        #
+        # @return [String, nil] entity type identifier for the given entity type
+        def get_entity_type_identifier(type)
+          return type if (type =~ URI::ABS_URI) || (type && type.start_with?('/'))
+
+          collection = @model.get(Occi::Core::Entity.kind.type_identifier)
+          e_kinds = collection.kinds.to_a.select { |e| e.term == type }
+          tis = e_kinds.collect { |e| e.type_identifier }
+          tis.uniq!
+
+          if tis.length > 1
+            raise Occi::Api::Client::Errors::AmbiguousNameError,
+                  "Entity type #{type.inspect} is ambiguous, use a type identifier!"
+          end
+
+          tis.first
         end
 
         # Retrieves all available resource types.
@@ -259,9 +380,8 @@ module Occi
         #
         # @return [Array<String>] list of available resource types in a human-readable format
         def get_resource_types
-          Occi::Log.debug("Getting resource types ...")
-          collection = @model.get Occi::Core::Resource.kind
-          collection.kinds.collect { |kind| kind.term }
+          collection = @model.get(Occi::Core::Resource.kind.type_identifier)
+          collection.kinds.to_a.collect { |kind| kind.term }
         end
 
         # Retrieves all available resource type identifiers.
@@ -274,7 +394,30 @@ module Occi
         #
         # @return [Array<String>] list of available resource types in a Occi ID format
         def get_resource_type_identifiers
-          get_entity_types_related_to Occi::Core::Resource.kind.type_identifier
+          get_kind_type_identifiers_related_to Occi::Core::Resource.kind.type_identifier
+        end
+
+        # Retrieves available resource type identifier for the given resource type.
+        #
+        # @example
+        #    client.get_resource_type_identifier("compute")
+        #     # => 'http://schemas.ogf.org/occi/infrastructure#compute'
+        #
+        # @return [String, nil] resource type identifier for the given resource type
+        def get_resource_type_identifier(type)
+          return type if (type =~ URI::ABS_URI) || (type && type.start_with?('/'))
+
+          collection = @model.get(Occi::Core::Resource.kind.type_identifier)
+          r_kinds = collection.kinds.to_a.select { |r| r.term == type }
+          tis = r_kinds.collect { |r| r.type_identifier }
+          tis.uniq!
+
+          if tis.length > 1
+            raise Occi::Api::Client::Errors::AmbiguousNameError,
+                  "Resource type #{type.inspect} is ambiguous, use a type identifier!"
+          end
+
+          tis.first
         end
 
         # Retrieves all available link types.
@@ -284,9 +427,8 @@ module Occi
         #
         # @return [Array<String>] list of available link types in a human-readable format
         def get_link_types
-          Occi::Log.debug("Getting link types ...")
-          collection = @model.get Occi::Core::Link.kind
-          collection.kinds.collect { |kind| kind.term }
+          collection = @model.get(Occi::Core::Link.kind.type_identifier)
+          collection.kinds.to_a.collect { |kind| kind.term }
         end
 
         # Retrieves all available link type identifiers.
@@ -298,7 +440,30 @@ module Occi
         #
         # @return [Array<String>] list of available link types in a OCCI ID format
         def get_link_type_identifiers
-          get_entity_types_related_to Occi::Core::Link.kind.type_identifier
+          get_kind_type_identifiers_related_to Occi::Core::Link.kind.type_identifier
+        end
+
+        # Retrieves available link type identifier for the given link type.
+        #
+        # @example
+        #    client.get_link_type_identifier("storagelink")
+        #     # => 'http://schemas.ogf.org/occi/infrastructure#storagelink'
+        #
+        # @return [String, nil] link type identifier for the given link type
+        def get_link_type_identifier(type)
+          return type if (type =~ URI::ABS_URI) || (type && type.start_with?('/'))
+
+          collection = @model.get(Occi::Core::Link.kind.type_identifier)
+          l_kinds = collection.kinds.to_a.select { |r| r.term == type }
+          tis = l_kinds.collect { |r| r.type_identifier }
+          tis.uniq!
+
+          if tis.length > 1
+            raise Occi::Api::Client::Errors::AmbiguousNameError,
+                  "Link type #{type.inspect} is ambiguous, use a type identifier!"
+          end
+
+          tis.first
         end
 
         # Looks up a mixin using its name and, optionally, a type as well.
@@ -404,16 +569,16 @@ module Occi
         # @return [Occi::Core::Mixins] collection of available mixins
         def get_mixins(type = nil)
           unless type.blank?
-            unless get_mixin_types.include?(type) || get_mixin_type_identifiers.include?(type)
+            type_id = get_mixin_type_identifier(type)
+            unless type_id
               raise ArgumentError,
                     "There is no such mixin type registered in the model! #{type.inspect}"
             end
 
-            type = get_mixin_type_identifier(type) if get_mixin_types.include?(type)
-            mixins = @model.mixins.to_a.select { |m| m.related_to?(type) }
+            mixins = @model.mixins.to_a.select { |m| m.related_to?(type_id) }
 
             # drop the type mixin itself
-            mixins.delete_if { |m| m.type_identifier == type }
+            mixins.delete_if { |m| m.type_identifier == type_id }
           else
             # we did not get a type, return all mixins
             mixins = Occi::Core::Mixins.new(@model.mixins)
@@ -479,8 +644,18 @@ module Occi
         #
         # @return [String, nil] mixin type identifier for the given mixin type
         def get_mixin_type_identifier(type)
-          mixins = get_mixins.to_a.select { |m| m.term == type }
-          mixins.collect { |m| m.type_identifier }.first
+          return type if (type =~ URI::ABS_URI) || (type && type.start_with?('/'))
+
+          mixins = @model.mixins.to_a.select { |m| m.term == type }
+          tis = mixins.collect { |m| m.type_identifier }
+          tis.uniq!
+
+          if tis.length > 1
+            raise Occi::Api::Client::Errors::AmbiguousNameError,
+                  "Mixin type #{type.inspect} is ambiguous, use a type identifier!"
+          end
+
+          tis.first
         end
 
         # Retrieves available os_tpls from the model.
@@ -490,7 +665,7 @@ module Occi
         #
         # @return [Occi::Core::Mixins] collection containing all registered OS templates
         def get_os_templates
-          get_mixins "http://schemas.ogf.org/occi/infrastructure#os_tpl"
+          get_mixins Occi::Infrastructure::OsTpl.mixin.type_identifier
         end
         alias_method :get_os_tpls, :get_os_templates
 
@@ -501,53 +676,90 @@ module Occi
         #
         # @return [Occi::Core::Mixins] collection containing all registered resource templates
         def get_resource_templates
-          get_mixins "http://schemas.ogf.org/occi/infrastructure#resource_tpl"
+          get_mixins Occi::Infrastructure::ResourceTpl.mixin.type_identifier
         end
         alias_method :get_resource_tpls, :get_resource_templates
 
-        # Returns the path for a given resource type identifier
+        # Returns the path for a given kind type identifier
         #
         # @example
-        #    path_for_resource_type "http://schemas.ogf.org/occi/infrastructure#compute"
+        #    path_for_kind_type_identifier "http://schemas.ogf.org/occi/infrastructure#compute"
         #     # => "/compute/"
-        #    path_for_resource_type "http://localhost:3300/compute/35ad4f45gsf-gsfg524s6gsfg-sfgsf4gsfg"
+        #    path_for_kind_type_identifier "http://localhost:3300/compute/35ad4f45gsf-gsfg524s6gsfg-sfgsf4gsfg"
         #     # => "/compute/35ad4f45gsf-gsfg524s6gsfg-sfgsf4gsfg"
         #
-        # @param [String] resource type identifier
+        # @param [String] kind type identifier
         # @return [String] 
-        def path_for_resource_type(resource_type_identifier)
-          return "/" if resource_type_identifier.nil? || resource_type_identifier == "/"
-
-          kinds = @model.kinds.select { |kind| kind.term == resource_type_identifier }
-          if kinds.any?
-            #we got an type identifier
-            path = "/" + kinds.first.type_identifier.split('#').last + "/"
-          elsif resource_type_identifier.start_with?(@endpoint) || resource_type_identifier.start_with?('/')
-            #we got an resource link
-            path = sanitize_resource_link(resource_type_identifier)
-          else
-            raise "Unknown resource identifier! #{resource_type_identifier.inspect}"
+        def path_for_kind_type_identifier(kind_type_identifier)
+          raise ArgumentError,
+                "Kind type identifier is a required argument!" if kind_type_identifier.blank?
+
+          if kind_type_identifier.start_with?(@endpoint.to_s) || kind_type_identifier.start_with?('/')
+            #we got an instance link
+            return sanitize_instance_link(kind_type_identifier)
+          end
+
+          kind_type_id = get_kind_type_identifier(kind_type_identifier)
+          unless kind_type_id
+            raise ArgumentError,
+                  "There is no such kind type registered in the model! #{kind_type_identifier.inspect}"
+          end
+
+          kinds = @model.kinds.select { |kind| kind.type_identifier == kind_type_id }
+          path_for_instance(kinds.first)
+        end
+
+        # Returns the path for a given instance, instances not providing
+        # path information will raise an exception.
+        #
+        # @example
+        #    path_for_instance Occi::Infrastructure::Network.new
+        #     # => "/network/35ad4f45gsf-gsfg524s6gsfg-sfgsf4gsfg"
+        #    path_for_instance Occi::Infrastructure::Compute.new
+        #     # => "/compute/35ad4f45gsf-gsfg524s6gsfg-sfgsf4gsfg"
+        #    path_for_instance Occi::Core::Mixin.new
+        #     # => "/mixin/my_mixin/"
+        #    path_for_instance Occi::Infrastructure::Storagelink.new
+        #     # => "/link/storagelink/35ad4f45gsf-gsfg524s6gsfg-sfgsf4gsfg"
+        #
+        # @param [Object] instance
+        # @return [String] path for the given instance
+        def path_for_instance(instance)
+          unless instance.respond_to?(:location)
+            raise Occi::Api::Client::Errors::TypeMismatchError,
+                  "Expected an instance responding to #location, " \
+                  "got #{instance.class.name.inspect}"
+          end
+
+          if instance.location.blank?
+            raise Occi::Api::Client::Errors::LocationError,
+                  "Instance of #{instance.class.name.inspect} has " \
+                  "an empty location"
           end
+
+          instance.location
         end
 
-        # Extracts the resource path from a resource link. It will remove the leading @endpoint
+        # Extracts path from an instance link. It will remove the leading @endpoint
         # and replace it with a slash.
         #
         # @example
-        #    sanitize_resource_link "http://localhost:3300/compute/35ad4f45gsf-gsfg524s6gsfg-sfgsf4gsfg"
+        #    sanitize_instance_link "http://localhost:3300/compute/35ad4f45gsf-gsfg524s6gsfg-sfgsf4gsfg"
         #     # => "/compute/35ad4f45gsf-gsfg524s6gsfg-sfgsf4gsfg"
-        #    sanitize_resource_link "/compute/35ad4f45gsf-gsfg524s6gsfg-sfgsf4gsfg"
+        #    sanitize_instance_link "/compute/35ad4f45gsf-gsfg524s6gsfg-sfgsf4gsfg"
         #     # => "/compute/35ad4f45gsf-gsfg524s6gsfg-sfgsf4gsfg"
         #
-        # @param [String] string containing the full resource link
+        # @param [String] string containing the full instance link
         # @return [String] extracted path, with a leading slash
-        def sanitize_resource_link(resource_link)
+        def sanitize_instance_link(instance_link)
           # everything starting with '/' is considered to be a resource path
-          return resource_link if resource_link.start_with? '/'
+          return instance_link if instance_link.start_with? '/'
 
-          raise "Resource link #{resource_link.inspect} is not valid!" unless resource_link.start_with? @endpoint
+          unless instance_link.start_with?(@endpoint.to_s)
+            raise ArgumentError, "Resource link #{instance_link.inspect} is not valid!"
+          end
 
-          resource_link.gsub @endpoint, '/'
+          URI(instance_link).request_uri
         end
 
         protected
@@ -560,29 +772,36 @@ module Occi
         # are: ["basic", "digest", "x509", "none"]
         #
         # @example
-        #    set_auth { :type => "none" }
-        #    set_auth { :type => "basic", :username => "123", :password => "321" }
-        #    set_auth { :type => "digest", :username => "123", :password => "321" }
-        #    set_auth { :type => "x509", :user_cert => "~/cert.pem",
+        #    get_auth { :type => "none" }
+        #    get_auth { :type => "basic", :username => "123", :password => "321" }
+        #    get_auth { :type => "digest", :username => "123", :password => "321" }
+        #    get_auth { :type => "x509", :user_cert => "~/cert.pem",
         #                  :user_cert_password => "321", :ca_path => nil }
         #
         # @param [Hash] authentication options
         # @param [Boolean] allow fallback-only options
-        def set_auth(auth_options, fallback = false); end
+        # @return [Hash] transformed hash with authN information
+        def get_auth(auth_options, fallback = false)
+          raise Occi::Api::Client::Errors::NotImplementedError, "#{__method__} is just a stub!"
+        end
 
         # Attempts to establish a preliminary connection with the server
         # to verify provided credentials and perform fallback authN
-        # if necessary. Has to be invoked after set_auth
-        def preauthenticate; end
+        # if necessary. Has to be invoked after @auth_options have been set.
+        def preauthenticate
+          raise Occi::Api::Client::Errors::NotImplementedError, "#{__method__} is just a stub!"
+        end
 
         # Sets media type. Will choose either application/occi+json or text/plain
         # based on the formats supported by the server.
         #
         # @example
-        #    set_media_type # => 'application/occi+json'
+        #    get_media_type # => 'application/occi+json'
         #
         # @return [String] chosen media type
-        def set_media_type(force_type = nil); end
+        def get_media_type(force_type = nil)
+          raise Occi::Api::Client::Errors::NotImplementedError, "#{__method__} is just a stub!"
+        end
 
         ##############################################################################
         ######## STUBS END
@@ -592,40 +811,52 @@ module Occi
         # instances to the rOCCI client.
         #
         # @example
-        #    set_logger { :out => STDERR, :level => Occi::Log::WARN, :logger => nil }
+        #    get_logger { :out => STDERR, :level => Occi::Log::WARN, :logger => nil }
         #
         # @param [Hash] logger options
-        def set_logger(log_options)
+        # @return [Occi::Log] instance of the logger
+        def get_logger(log_options)
           unless log_options[:logger] && log_options[:logger].kind_of?(Occi::Log)
-            @logger = Occi::Log.new(log_options[:out])
-            @logger.level = log_options[:level]
+            logger = Occi::Log.new(log_options[:out])
+            logger.level = log_options[:level]
+          else
+            logger = log_options[:logger]
           end
+
+          logger
         end
 
-        # Checks whether the given endpoint URI is valid and adds a trailing
-        # slash if necessary.
+        # Checks whether the given endpoint URI is valid and converts it
+        # to a URI instance.
         #
         # @example
-        #    set_endpoint "http://localhost:3300" # => "http://localhost:3300/"
+        #    get_endpoint_uri "http://localhost:3300" # => #<URI::*>
         #
         # @param [String] endpoint URI in a non-canonical string
-        # @return [String] canonical endpoint URI in a string, with a trailing slash
-        def set_endpoint(endpoint)
-          raise 'Endpoint not a valid URI' unless (endpoint =~ URI::ABS_URI)
-          @endpoint = endpoint.chomp('/') + '/'
+        # @return [URI] canonical endpoint URI
+        def get_endpoint_uri(endpoint)
+          unless endpoint =~ URI::ABS_URI
+            raise "Endpoint not a valid absolute URI! #{endpoint.inspect}"
+          end
+
+          # normalize URIs, remove trailing slashes
+          endpoint = URI(endpoint)
+          endpoint.path = endpoint.path.gsub(/\/+/, '/').chomp('/')
+
+          endpoint
         end
 
         # Creates an Occi::Model from data retrieved from the server.
         #
         # @example
-        #    model = get('/-/')
-        #    set_model model # => #<Occi::Model>
+        #    model_collection = get('/-/')
+        #    get_model model_collection # => #<Occi::Model>
         #
         # @param [Occi::Collection] parsed representation of server's model
         # @return [Occi::Model] Model instance
-        def set_model(model)
+        def get_model(model_collection)
           # build model
-          @model = Occi::Model.new(model)
+          Occi::Model.new(model_collection)
         end
 
         # Returns mixin type identifiers for os_tpl mixins

data/lib/occi/api/client/client_http.rb

@@ -88,8 +88,8 @@ module Occi
           
           # get model information from the endpoint
           # and create Occi::Model instance
-          model = get('/-/')
-          set_model model
+          model_collection = get('/-/')
+          @model = get_model(model_collection)
 
           # auto-connect?
           @connected = @options[:auto_connect]
@@ -98,33 +98,18 @@ module Occi
         # @see Occi::Api::Client::ClientBase
         def list(resource_type_identifier=nil)
           if resource_type_identifier
-            # convert type to type identifier
-            kinds = @model.kinds.select {
-              |kind| kind.term == resource_type_identifier
-            }
-            if kinds.any?
-              resource_type_identifier = kinds.first.type_identifier
-            end
-
-            raise 'Unkown resource type identifier!' unless resource_type_identifier
-            unless @model.get_by_id resource_type_identifier
-              raise "Resource type identifier not allowed with this model! [#{resource_type_identifier}]"
-            end
-
-            # split the type identifier and get the most important part
-            uri_part = resource_type_identifier.split('#').last
-
-            # request uri-list from the server
-            path = uri_part + '/'
+            resource_type_identifier = get_resource_type_identifier(resource_type_identifier)
+            path = path_for_kind_type_identifier(resource_type_identifier)
           end
 
           path = '/' unless path
+          path = "#{@endpoint.to_s}#{path}"
 
           headers = self.class.headers.clone
           headers['Accept'] = 'text/uri-list'
 
           response = self.class.get(
-            @endpoint + path,
+            path,
             :headers => headers
           )
 
@@ -134,20 +119,13 @@ module Occi
 
         # @see Occi::Api::Client::ClientBase
         def describe(resource_type_identifier=nil)
-
-          # convert type to type identifier whenever possible
           if resource_type_identifier
-            kinds = @model.kinds.select {
-              |kind| kind.term == resource_type_identifier
-            }
-            if kinds.any?
-              resource_type_identifier = kinds.first.type_identifier
-            end
+            resource_type_identifier = get_resource_type_identifier(resource_type_identifier)
           end
 
           descriptions = Occi::Collection.new
 
-          if resource_type_identifier.nil?
+          if resource_type_identifier.blank?
             # no filters, describe all available resources
             descriptions.merge! get('/')
           elsif @model.get_by_id(resource_type_identifier)
@@ -157,13 +135,13 @@ module Occi
 
             # make the requests
             locations.each do |location|
-              descriptions.merge! get(sanitize_resource_link(location))
+              path = sanitize_instance_link(location)
+              descriptions.merge! get(path)
             end
-          elsif resource_type_identifier.start_with?(@endpoint) || resource_type_identifier.start_with?('/')
-            # this is a link of a specific resource (obsolute or relative)
-            descriptions.merge! get(sanitize_resource_link(resource_type_identifier))
           else
-            raise "Unkown resource type identifier! [#{resource_type_identifier}]"
+            # this is a link of a specific resource (absolute or relative)
+            path = sanitize_instance_link(resource_type_identifier)
+            descriptions.merge! get(path)
           end
 
           descriptions.resources
@@ -171,30 +149,27 @@ module Occi
 
         # @see Occi::Api::Client::ClientBase
         def create(entity)
+          raise "#{entity.class.name.inspect} not an entity!" unless entity.kind_of? Occi::Core::Entity
 
-          raise "#{entity} not an entity!" unless entity.kind_of? Occi::Core::Entity
-
-          Occi::Log.debug "Entity kind: #{entity.kind}"
-          kind = entity.kind
-          raise "No kind found for #{entity}" unless kind
+          Occi::Log.debug "Entity kind: #{entity.kind.type_identifier.inspect}"
+          raise "No kind found for #{entity.inspect}" unless entity.kind
 
           # get location for this kind of entity
-          Occi::Log.debug "Kind location: #{entity.kind.location}"
-          location = kind.location
+          path = path_for_kind_type_identifier(entity.kind.type_identifier)
           collection = Occi::Collection.new
 
           # is this entity a Resource or a Link?
-          Occi::Log.debug "Entity class: #{entity.class.name}"
+          Occi::Log.debug "Entity class: #{entity.class.name.inspect}"
           collection.resources << entity if entity.kind_of? Occi::Core::Resource
           collection.links << entity if entity.kind_of? Occi::Core::Link
 
           # make the request
-          post location, collection
+          post path, collection
         end
 
         # @see Occi::Api::Client::ClientBase
         def deploy(location)
-          raise "File #{location} does not exist!" unless File.exist? location
+          raise "File #{location.inspect} does not exist!" unless File.exist? location
 
           file = File.read(location)
 
@@ -209,12 +184,14 @@ module Occi
 
         # @see Occi::Api::Client::ClientBase
         def deploy_ovf(descriptor)
-          media_types = self.class.head(@endpoint).headers['accept'].to_s
+          media_types = self.class.head(@endpoint.to_s).headers['accept'].to_s
 
+          path = path_for_kind_type_identifier(Occi::Infrastructure::Compute.type_identifier)
+          path = "#{@endpoint.to_s}#{path}"
           if media_types.include? 'application/ovf'
             headers = self.class.headers.clone
             headers['Content-Type'] = 'application/ovf'
-            self.class.post(@endpoint + '/compute/',
+            self.class.post(path,
                             :body => descriptor,
                             :headers => headers)
           else
@@ -224,12 +201,14 @@ module Occi
 
         # @see Occi::Api::Client::ClientBase
         def deploy_ova(descriptor)
-          media_types = self.class.head(@endpoint).headers['accept'].to_s
+          media_types = self.class.head(@endpoint.to_s).headers['accept'].to_s
 
+          path = path_for_kind_type_identifier(Occi::Infrastructure::Compute.type_identifier)
+          path = "#{@endpoint.to_s}#{path}"
           if media_types.include? ' application/ova '
             headers = self.class.headers.clone
             headers['Content-Type'] = 'application/ova'
-            self.class.post(@endpoint + '/compute/',
+            self.class.post(path,
                             :body => descriptor,
                             :headers => headers)
           else
@@ -239,47 +218,31 @@ module Occi
 
         # @see Occi::Api::Client::ClientBase
         def delete(resource_type_identifier)
-          raise 'Resource not provided!' unless resource_type_identifier
-          path = path_for_resource_type(resource_type_identifier)
+          raise 'Resource not provided!' if resource_type_identifier.blank?
+          path = path_for_kind_type_identifier(resource_type_identifier)
 
-          Occi::Log.debug("Deleting #{path} ...")
+          Occi::Log.debug("Deleting #{path.inspect} for #{resource_type_identifier.inspect}")
           del path
         end
 
         # @see Occi::Api::Client::ClientBase
-        def trigger(resource_type_identifier, action)
+        def trigger(resource_type_identifier, action_instance)
           # TODO: not tested
-          raise 'Resource not provided!' unless resource_type_identifier
-          type_identifiers = @model.kinds.select {
-            |kind| kind.term == resource_type_identifier
-          }
-
-          if type_identifiers.any?
-            type_identifier = @model.kinds.select {
-              |kind| kind.term == resource_type_identifier
-            }.first.type_identifier
-
-            location = @model.get_by_id(type_identifier).location
-            resource_type_identifier = @endpoint + location
-          end
-
-          raise "Unknown resource identifier! #{resource_type_identifier}" unless resource_type_identifier.start_with? @endpoint
+          raise 'Resource not provided!' if resource_type_identifier.blank?
 
-          # encapsulate the acion in a collection
-          collection = Occi::Collection.new
-          scheme, term = action.split('#')
-          collection.actions << Occi::Core::Action.new(scheme + '#', term)
+          #
+          resource_type_identifier = get_resource_type_identifier(resource_type_identifier)
+          path = path_for_kind_type_identifier(resource_type_identifier)
 
           # make the request
-          path = sanitize_resource_link(resource_type_identifier) + '?action=' + term
-          post path, collection
+          post path, action_instance
         end
 
         # @see Occi::Api::Client::ClientBase
         def refresh
           # re-download the model from the server
-          model = get('/-/')
-          set_model model
+          model_collection = get('/-/')
+          @model = get_model(model_collection)
         end
 
         private
@@ -294,10 +257,10 @@ module Occi
         # @param [String] path for the GET request
         # @param [Occi::Collection] collection of filters
         # @return [Occi::Collection] parsed result of the request
-        def get(path='', filter=nil)
-          # remove the leading slash
-          path = path.gsub(/\A\//, '')
-
+        def get(path='/', filter=nil)
+          relative_path = path
+          path = "#{@endpoint.to_s}#{path}"
+          # apply filters if present
           response = if filter
             categories = filter.categories.collect { |category| category.to_text }.join(',')
             attributes = filter.entities.collect { |entity| entity.attributes.combine.collect { |k, v| k + '=' + v } }.join(',')
@@ -307,28 +270,28 @@ module Occi
             headers['Category'] = categories unless categories.empty?
             headers['X-OCCI-Attributes'] = attributes unless attributes.empty?
 
-            self.class.get(@endpoint + path, :headers => headers)
+            self.class.get(path, :headers => headers)
           else
-            self.class.get(@endpoint + path)
+            self.class.get(path)
           end
 
           response_msg = response_message response
           raise "HTTP GET failed! #{response_msg}" unless response.code.between? 200, 300
 
-          Occi::Log.debug "Response location: #{('/' + path).match(/\/.*\//).to_s}"
-          kind = @model.get_by_location(('/' + path).match(/\/.*\//).to_s) if @model
+          Occi::Log.debug "Response location: #{relative_path.inspect}"
+          kind = @model.get_by_location(relative_path) if @model
 
-          Occi::Log.debug "Response kind: #{kind}"
+          Occi::Log.debug "Response kind: #{kind.inspect}"
 
-          if kind
-            kind.related_to? Occi::Core::Resource ? entity_type = Occi::Core::Resource : entity_type = nil
-            entity_type = Occi::Core::Link if kind.related_to? Occi::Core::Link
+          entity_type = nil
+          if kind && kind.related_to?(Occi::Core::Link)
+            entity_type = Occi::Core::Link
           end
 
           entity_type = Occi::Core::Resource unless entity_type
 
-          Occi::Log.debug "Parser call: #{response.content_type} #{path.include?('-/')} #{entity_type} #{response.headers.inspect}"
-          collection = Occi::Parser.parse(response.content_type, response.body, path.include?('-/'), entity_type, response.headers)
+          Occi::Log.debug "Parser call: #{response.content_type} #{path.include?('/-/')} #{entity_type} #{response.headers.inspect}"
+          collection = Occi::Parser.parse(response.content_type, response.body, path.include?('/-/'), entity_type, response.headers)
 
           Occi::Log.debug "Parsed collection: empty? #{collection.empty?}"
           collection
@@ -350,27 +313,28 @@ module Occi
         # @param [Occi::Collection] resource data to be POSTed
         # @return [String] URI location
         def post(path, collection)
-          # remove the leading slash
-          path = path.gsub(/\A\//, '')
+          raise ArgumentError, "Path is a required argument!" if path.blank?
 
           headers = self.class.headers.clone
           headers['Content-Type'] = @media_type
 
+          path = "#{@endpoint.to_s}#{path}"
+
           response = case @media_type
           when 'application/occi+json'
-            self.class.post(@endpoint + path,
+            self.class.post(path,
                             :body => collection.to_json,
                             :headers => headers)
           when 'text/occi'
-            self.class.post(@endpoint + path,
+            self.class.post(path,
                             :headers => collection.to_header.merge(headers))
           else
-            self.class.post(@endpoint + path,
+            self.class.post(path,
                             :body => collection.to_text,
                             :headers => headers)
           end
 
-          response_msg = response_message response
+          response_msg = response_message(response)
 
           case response.code
           when 200
@@ -403,27 +367,28 @@ module Occi
         # @param [Occi::Collection] resource data to send
         # @return [Occi::Collection] parsed result of the request
         def put(path, collection)
-          # remove the leading slash
-          path = path.gsub(/\A\//, '')
+          raise ArgumentError, "Path is a required argument!" if path.blank?
 
           headers = self.class.headers.clone
           headers['Content-Type'] = @media_type
 
+          path = "#{@endpoint.to_s}#{path}"
+
           response = case @media_type
           when 'application/occi+json'
-            self.class.post(@endpoint + path,
+            self.class.post(path,
                             :body => collection.to_json,
                             :headers => headers)
           when 'text/occi'
-            self.class.post(@endpoint + path,
+            self.class.post(path,
                             :headers => collection.to_header.merge(headers))
           else
-            self.class.post(@endpoint + path,
+            self.class.post(path,
                             :body => collection.to_text,
                             :headers => headers)
           end
 
-          response_msg = response_message response
+          response_msg = response_message(response)
 
           case response.code
           when 200, 201
@@ -442,38 +407,37 @@ module Occi
         # @param [Occi::Collection] collection of filters (currently NOT used)
         # @return [Boolean] status
         def del(path, filter=nil)
-          # remove the leading slash
-          path = path.gsub(/\A\//, '')
+          raise ArgumentError, "Path is a required argument!" if path.blank?
 
-          response = self.class.delete(@endpoint + path)
+          response = self.class.delete("#{@endpoint.to_s}#{path}")
 
-          response_msg = response_message response
+          response_msg = response_message(response)
           raise "HTTP DELETE failed! #{response_msg}" unless response.code.between? 200, 300
 
           true
         end
 
         # @see Occi::Api::Client::ClientBase
-        def set_logger(log_options)
-          super log_options
+        def get_logger(log_options)
+          logger = super(log_options)
+          self.class.debug_output $stderr if logger.level == Occi::Log::DEBUG
 
-          self.class.debug_output $stderr if log_options[:level] == Occi::Log::DEBUG
+          logger
         end
 
         # @see Occi::Api::Client::ClientBase
-        def set_auth(auth_options, fallback = false)
-          @auth_options = auth_options
-
-          case @auth_options[:type]
+        def get_auth(auth_options, fallback = false)
+          # select appropriate authN type
+          case auth_options[:type]
           when "basic"
-            @authn_plugin = Http::AuthnPlugins::Basic.new self, @auth_options
+            @authn_plugin = Http::AuthnPlugins::Basic.new self, auth_options
           when "digest"
-            @authn_plugin = Http::AuthnPlugins::Digest.new self, @auth_options
+            @authn_plugin = Http::AuthnPlugins::Digest.new self, auth_options
           when "x509"
-            @authn_plugin = Http::AuthnPlugins::X509.new self, @auth_options
+            @authn_plugin = Http::AuthnPlugins::X509.new self, auth_options
           when "keystone"
             raise ::Occi::Api::Client::Errors::AuthnError, "This authN method is for fallback only!" unless fallback
-            @authn_plugin = Http::AuthnPlugins::Keystone.new self, @auth_options
+            @authn_plugin = Http::AuthnPlugins::Keystone.new self, auth_options
           when "none", nil
             @authn_plugin = Http::AuthnPlugins::Dummy.new self
           else
@@ -481,6 +445,8 @@ module Occi
           end
 
           @authn_plugin.setup
+
+          auth_options
         end
 
         # @see Occi::Api::Client::ClientBase
@@ -495,7 +461,7 @@ module Occi
               @auth_options[:original_type] = @auth_options[:type]
               @auth_options[:type] = @authn_plugin.fallbacks.first
 
-              set_auth @auth_options, true
+              @auth_options = get_auth(@auth_options, true)
               @authn_plugin.authenticate
             else
               raise e
@@ -504,34 +470,41 @@ module Occi
         end
 
         # @see Occi::Api::Client::ClientBase
-        def set_media_type(force_type = nil)
+        def get_media_type(force_type = nil)
           # force media_type if provided
-          if force_type
+          unless force_type.blank?
             self.class.headers 'Accept' => force_type
-            @media_type = force_type
+            media_type = force_type
           else
-            media_types = self.class.head(@endpoint).headers['accept']
-            Occi::Log.debug("Available media types: #{media_types}")
-            @media_type = case media_types
+            media_types = self.class.head(@endpoint.to_s).headers['accept']
+
+            Occi::Log.debug("Available media types: #{media_types.inspect}")
+            media_type = case media_types
             when /application\/occi\+json/
               'application/occi+json'
+            when /application\/occi\+xml/
+              'application/occi+xml'
+            when /text\/occi/
+              'text/occi'
             else
               'text/plain'
             end
           end
+
+          media_type
         end
 
         # Generates a human-readable response message based on the HTTP response code.
         #
         # @example
-        #    response_message self.class.delete(@endpoint + path)
+        #    response_message self.class.delete(@endpoint.to_s + path)
         #     # =>  'HTTP Response status: [200] OK'
         #
         # @param [HTTParty::Response] HTTParty response object
         # @return [String] message
         def response_message(response)
           @last_response = response
-          'HTTP Response status: [' + response.code.to_s + '] ' + reason_phrase(response.code)
+          "HTTP Response status: [#{response.code.to_s}] #{reason_phrase(response.code)}"
         end
 
         # Converts HTTP response codes to human-readable phrases.

data/lib/occi/api/client/errors.rb

@@ -1 +1,4 @@
-require 'occi/api/client/errors/authn_error'
+module Occi::Api::Client::Errors; end
+
+# load all
+Dir[File.join(File.dirname(__FILE__), 'errors', '*.rb')].each { |file| require file.gsub('.rb', '') }

data/lib/occi/api/client/errors/ambiguous_name_error.rb

@@ -0,0 +1,5 @@
+module Occi::Api::Client::Errors
+
+  class AmbiguousNameError < RuntimeError; end
+
+end

data/lib/occi/api/client/errors/authn_error.rb

@@ -1,7 +1,5 @@
-module Occi::Api::Client
-  module Errors
+module Occi::Api::Client::Errors
 
-    class AuthnError < RuntimeError; end
+  class AuthnError < RuntimeError; end
 
-  end
 end

data/lib/occi/api/client/errors/location_error.rb

@@ -0,0 +1,5 @@
+module Occi::Api::Client::Errors
+
+  class LocationError < RuntimeError; end
+
+end

data/lib/occi/api/client/errors/not_implemented_error.rb

@@ -0,0 +1,5 @@
+module Occi::Api::Client::Errors
+
+  class NotImplementedError < NotImplementedError; end
+
+end

data/lib/occi/api/client/errors/type_mismatch_error.rb

@@ -0,0 +1,5 @@
+module Occi::Api::Client::Errors
+
+  class TypeMismatchError < ArgumentError; end
+
+end

data/lib/occi/api/client/http/authn_plugins/base.rb

@@ -16,7 +16,7 @@ module Occi::Api::Client
         def setup(options = {}); end
 
         def authenticate(options = {})
-          response = @env_ref.class.head "#{@env_ref.endpoint}-/"
+          response = @env_ref.class.head("#{@env_ref.endpoint.to_s}/-/")
           raise ::Occi::Api::Client::Errors::AuthnError, "Authentication failed with code #{response.code.to_s}!" unless response.success?
         end
 

data/lib/occi/api/client/http/authn_plugins/keystone.rb

@@ -18,7 +18,7 @@ module Occi::Api::Client
 
         def authenticate(options = {})
           # OCCI-OS doesn't support HEAD method!
-          response = @env_ref.class.get "#{@env_ref.endpoint}-/"
+          response = @env_ref.class.get "#{@env_ref.endpoint.to_s}/-/"
           raise ::Occi::Api::Client::Errors::AuthnError,
                 "Authentication failed with code #{response.code.to_s}!" unless response.success?
         end
@@ -26,7 +26,7 @@ module Occi::Api::Client
         private
 
         def set_keystone_base_url
-          response = @env_ref.class.head "#{@env_ref.endpoint}-/"
+          response = @env_ref.class.head "#{@env_ref.endpoint.to_s}/-/"
           Occi::Log.debug response.inspect
 
           return if response.success?

data/lib/occi/api/version.rb

@@ -1,5 +1,5 @@
 module Occi
   module Api
-    VERSION = "4.2.0.beta.2" unless defined?(::Occi::Api::VERSION)
+    VERSION = "4.2.0.beta.3" unless defined?(::Occi::Api::VERSION)
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: occi-api
 version: !ruby/object:Gem::Version
-  version: 4.2.0.beta.2
+  version: 4.2.0.beta.3
   prerelease: 6
 platform: ruby
 authors:
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-04 00:00:00.000000000 Z
+date: 2013-12-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: occi-core
@@ -87,7 +87,11 @@ files:
 - lib/occi/api/client/client_base.rb
 - lib/occi/api/client/client_http.rb
 - lib/occi/api/client/errors.rb
+- lib/occi/api/client/errors/ambiguous_name_error.rb
 - lib/occi/api/client/errors/authn_error.rb
+- lib/occi/api/client/errors/location_error.rb
+- lib/occi/api/client/errors/not_implemented_error.rb
+- lib/occi/api/client/errors/type_mismatch_error.rb
 - lib/occi/api/client/http/authn_plugins.rb
 - lib/occi/api/client/http/authn_plugins/base.rb
 - lib/occi/api/client/http/authn_plugins/basic.rb