mikyung 0.7.0

data/LICENSE

@@ -0,0 +1,17 @@
+/***
+ * Copyright (c) 2009 Caelum - www.caelum.com.br/opensource
+ * All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); 
+ * you may not use this file except in compliance with the License. 
+ * You may obtain a copy of the License at 
+ * 
+ * 	http://www.apache.org/licenses/LICENSE-2.0 
+ * 
+ * Unless required by applicable law or agreed to in writing, software 
+ * distributed under the License is distributed on an "AS IS" BASIS, 
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
+ * See the License for the specific language governing permissions and 
+ * limitations under the License. 
+ */
+

data/README.textile

@@ -0,0 +1,149 @@
+h2. The need for a Rest client
+
+*Let media types and relations* drive your client, as REST is.
+
+But, Http, Verbs, Media types, Representations, Error codes, retrials, conditional requests, there are so many things we should do to implement a REST system.
+
+Built upon Restfulie, *Mikyung* provides a layer of client generalization that gives you enough room to configure how your client should behave in different situations and make them work with different servers.
+
+The following example can be executed from the example directory, just *clone and rake spec* it.
+
+h2. Simple example
+
+In order to create a REST client, anyone needs to have a goal and a sequence of steps that we can follow to pursue this goal. Mikyung implements a simple framework so you can define your goal and steps, and let everything else happen.
+
+As a simple example, let's try to buy something in *any* REST server:
+
+<pre>Mikyung.new(Buy.new).run('http://openbuystore.caelumobjects.com:/')</pre>
+
+This is how you awake a REST client, that will start executing a series of requests until its objective is achieved.
+
+If we want to achieve the same goal in another system, Mikyung and Restfulie will handle it all, just change the entry point URI. All its required is that your client understands the server's media types.
+
+And now, our goal is to have a payment that is paid:
+
+<pre>
+	class Buy < RelationDrivenObjective
+
+	  def completed?(resource)
+	    resource.respond_to?(:status) && resource.status == "paid"
+	  end
+
+	  executes FinishesOrder, :when => has_relation?(:payment)
+	  executes PickProduct, :when => has_relation?(:basket)
+	  executes SearchProducts, :when => has_relation?(:search)
+
+	end
+</pre>
+
+If there is a search relation, let's search for our items:
+
+<pre>
+class SearchProducts
+  def execute(entry)
+    entry.search.get("rest")
+  end
+end
+</pre>
+
+How will it work? Restfulie will content negotiate and discover that your server understands, lets say, opensearch. Using an OpenSearch media type handler, it will serialize your object to execute the query.
+
+If your server understood Yahoo's YQL and provided an YQL specification handler, Restfulie would execute the query using YQL.
+
+The next step is to choose the cheapest and the first product on the list:
+
+<pre>
+class PickProduct
+
+  def execute(list)
+    
+    cheapest = list.entries...
+    
+    # adds the cheapest and the first product
+    basket = [{:id => cheapest.id, :quantity => 1}, {:id => list.entries[0].id, :quantity => 1}]
+    
+    list.basket.post!(basket)
+  end
+end
+</pre>
+
+Again, if your server implements a well known e-commerce media type, Restfulie will serialize and handle everything for you. If your server uses a custom one, you can create your own handler and contribute with our project (although REST systems should, as much as possible, stick to well known media types).
+
+Let's buy our products:
+
+<pre>
+class FinishesOrder
+  def execute(basket)
+    payment = {:creditcard_number => "4850000000000001", :creditcard_holder => "guilherme silveira", :creditcard_expires => "10/2020", :creditcard_code => "123", :amount => basket.price}
+    basket.payment.post!(payment)
+  end
+end
+</pre>
+
+Again, media type handling, content negotiation, retrials, everything is handled by Mikyung and Restfulie.
+
+Now you can rest... or keep reading
+
+h2. The power
+
+The above example should suffice to buy something in *any* REST system that contains the basket and payment process.
+
+h2. How?
+
+All you need to do is understand some media type that your server does. If the server understands well-known ones (as per the REST definition), contribute to Restfulie with your media type implementation.
+
+If the server understand a custom media type, it should be their job to provide a media type handler, as they did not follow any standard.
+
+Note that providing a media type handler does not mean that your client will follow some specific steps, but whenever it follow some steps, it will it as the media type described.
+
+h2. Team and Support
+
+Guilherme Silveira is behind Mikyung and support can be received through Restfulie's mailing lists.
+
+h2. Registering media types and much more
+
+Mikyung uses Restfulie so everything related with content type negotiation should be configured there.
+
+h2. Objective and Steps
+
+Everything related to objective, steps, error code handling, execution postponing can be configured or hacked into Mikyung.
+
+h2. Objective examples
+
+You can create your own objective builders, with the required conditions that your goal achiever requires.
+Mikyung provides one objective builder called *RelationDrivenObjective* to describe how to use it. The following example shows how to achieve a buying objective:
+
+[pre]
+class Buy < RelationDrivenObjective
+  
+  executes FinishesOrder, :when => has_relation(:payment)
+  executes PickProduct, :when => has_relation(:basket)
+  executes SearchProducts, :when => has_relation(:search)
+
+  def completed?(resource)
+    resource.respond_to?(:status) && resource.status == "paid"
+  end
+  
+end
+[/pre]
+
+
+A less declarative approach is to implement both the completed? and *next_step* methods:
+
+[pre]
+class Buy
+  
+  def completed?(resource)
+    resource.respond_to?(:status) && resource.status == "paid"
+  end
+  
+  def next_step(resource)
+    options = [ ["payment", FinishesOrder], ["basket", PickProduct], ["search", SearchProducts]]
+    step = options.find do |k|
+      resource.respond_to?(k.first)
+    end
+    step ? step.last : nil
+  end
+  
+end
+[/pre]

data/Rakefile

@@ -0,0 +1,63 @@
+require 'rubygems'
+require 'rubygems/specification'
+require 'rake'
+require 'rake/gempackagetask'
+require 'spec/rake/spectask'
+require 'rake/rdoctask'
+
+GEM = "mikyung"
+GEM_VERSION = "0.7.0"
+SUMMARY  = "Mikyung is a restful client built on top of Restfulie that allows real rest clients to be built."
+AUTHOR   = "Guilherme Silveira"
+EMAIL    = "guilherme.silveira@caelum.com.br"
+HOMEPAGE = "http://restfulie.caelumobjects.com"
+
+spec = Gem::Specification.new do |s|
+  s.name = GEM
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.summary = SUMMARY
+  s.require_paths = ['lib']
+  s.files = FileList['lib/**/*.rb', '[A-Z]*'].to_a
+  s.add_dependency("restfulie", [">= 0.7.0"])
+
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.homepage = HOMEPAGE
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+Rake::RDocTask.new("rdoc") do |rdoc|
+   rdoc.options << '--line-numbers' << '--inline-source'
+#   rdoc.rdoc_files.include('lib/**/**/*.rb')
+end
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |t|
+    t.files   = ['lib/restfulie/**/*.rb', 'README.textile']   # optional
+    # t.options = ['--any', '--extra', '--opts'] # optional
+  end
+rescue; end
+
+desc "Install the gem locally"
+task :install => [:package] do
+  sh %{gem install pkg/#{GEM}-#{GEM_VERSION} -l}
+end
+
+desc "Create a gemspec file"
+task :make_spec do
+  File.open("#{GEM}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end
+
+desc "Builds the project"
+task :build => :install
+
+desc "Default build will run specs"
+task :default => :install
+

data/lib/mikyung.rb

@@ -0,0 +1,84 @@
+class HasRelation
+  def initialize(rel)
+    @rel = rel
+  end
+  
+  def matches?(resource)
+    resource.respond_to?(@rel)
+  end
+end
+
+class RelationDrivenObjective
+
+  def self.executes(what, options = {})
+    internals << [options[:when], what]
+  end
+  
+  def self.has_relation?(rel)
+    HasRelation.new(rel)
+  end
+  
+  def internals
+    self.class.internals
+  end
+  
+  def next_step(resource)
+    step = internals.find do |k|
+      k.first.matches?(resource)
+    end
+    step ? step.last : nil
+  end
+
+  private
+
+  def self.internals
+    @steps ||= []
+  end
+
+end
+
+
+
+# iterates following a series of steps provided a goal and a starting uri.
+#
+# Mikyung.new(objective).run(uri)
+class Mikyung
+  
+  # initializes with a goal in mind
+  def initialize(goal)
+    @goal = goal
+  end
+
+  # keeps changing from a steady state to another until its goal has been achieved
+  def run(uri)
+    
+    current = Restfulie.at(uri).get!
+    Restfulie::Common::Logger.logger.debug current.response.body
+    
+    while(!@goal.completed?(current))
+      step = @goal.next_step(current)
+      raise "No step was found for #{current} with links #{current.links}" unless step
+      Restfulie::Common::Logger.logger.debug "Mikyung > next step will be #{step}"
+      current = try_to_execute(step.new, current, 3)
+    end
+    
+  end
+
+  private
+  
+  def try_to_execute(step, current, max_attempts)
+    raise "Unable to proceed when trying to #{step}" if max_attempts == 0
+
+    resource = step.execute(current)
+    if resource.response.code != 200
+      try_to_execute(step, max_attempts - 1)
+    else
+      Restfulie::Common::Logger.logger.debug resource.response.body
+      resource
+    end
+  end
+
+  def direct_execute(step, current, max_attempts)
+    step.execute(current)
+  end
+end

data/lib/opensearch_mediatype.rb

@@ -0,0 +1,54 @@
+class OpenSearchEngine
+  
+  def initialize(uri)
+    @description = Restfulie.accepts("application/opensearchdescription+xml").at(uri).get!
+  end
+  
+  def post!(terms)
+    urls = @description["OpenSearchDescription"]["Url"]
+    uri = urls["template"].gsub("{searchTerms}", terms).gsub("{startPage?}","1")
+    type = urls["type"]
+    Restfulie.at(uri).accepts(type).get!
+  end
+  
+  include Restfulie::Client::HTTP::RequestMarshaller
+  
+end
+
+
+module Restfulie::Common::Representation
+
+  class OpenSearch
+
+    cattr_reader :media_type_name
+    @@media_type_name = 'application/opensearchdescription+xml'
+
+    cattr_reader :headers
+    @@headers = { 
+      :get  => { 'Accept'       => media_type_name },
+      :post => { }
+    }
+
+    #Convert raw string to rAtom instances
+    def unmarshal(content)
+      Hash.from_xml(content)
+    end
+
+    def marshal(content)
+      content
+    end
+    
+    # prepares a link request element based on a relation.
+    def prepare_link_for(link)
+      if link.rel=="search"
+        OpenSearchEngine.new(link.href)
+      else
+        link
+      end
+    end
+    
+  end
+
+end
+
+Restfulie::Client::HTTP::RequestMarshaller.register_representation("application/opensearchdescription+xml", Restfulie::Common::Representation::OpenSearch)

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification 
+name: mikyung
+version: !ruby/object:Gem::Version 
+  version: 0.7.0
+platform: ruby
+authors: 
+- Guilherme Silveira
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-08 00:00:00 -03:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: restfulie
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.7.0
+    version: 
+description: 
+email: guilherme.silveira@caelum.com.br
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/mikyung.rb
+- lib/opensearch_mediatype.rb
+- LICENSE
+- Rakefile
+- README.textile
+has_rdoc: true
+homepage: http://restfulie.caelumobjects.com
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Mikyung is a restful client built on top of Restfulie that allows real rest clients to be built.
+test_files: []
+