Carioca

Content

Description

CARIOCA is Configuration Agent and Registry with Inversion Of Control for your Applications
Carioca provide a full IoC light Container for designing your applications
Carioca provide :
- a complete Configuration Agent
- A service Registry (base on IOC/DI pattern)

Installation

In a valid Ruby environment :

   $ sudo zsh
   # gem ins carioca

Implementation

  • [Carioca]
  • [Carioca::Services]
  • [Carioca:Services::Registry]

Utilisation

Carioca may be used to create Ruby applications, based on a service registry
Carioca come with somes builtin services :
  • logger : an Internal logger based on the logger gem.
  • Configuration : a Configuration Service, with Yaml percistance, and pretty accessors.
  • Debug : a Class Debugger, based on Proxy Design pattern and meta-programation like method_missing

Getting start

Preparing Gem

Just after Installation, Carioca :

$ gem ins bundler # if needed
$ bunlde gem myapp
$ cd myapp

Edit your myapp.gemspec, add this line in Gem::Specification bloc :

  gem.add_dependency 'carioca'
  gem.add_development_dependency 'rake'
  gem.add_development_dependency 'carioca'

Description and summary need to be changed to be correctly displayed on Rubygems.

so, execute bundle :

 $ bundle

Your environment, is ready to create your app

Prepare Carioca

 
$ mkdir config
$ mkdir bin

edit bin/myapp :

require 'rubygems'
require 'carioca'

registry = Carioca::Services::Registry.init :file => 'config/myservices.registry'

After, you could Run Carioca and discover Builtins Services, you need the write access to config path

$ ruby -e 'require "rubygems"; require "carioca"; reg = Carioca::Services::Registry.init :file => "config/myservices.registry"; reg.discover_builtins; reg.save!'
this create you, a New Registry config, with all builtins registered.
Default path :
  • config file : ./.config
  • log file : /tmp/log.file
    Carioca Registry is a Singleton, and services also be unique instance.

Now you could continue coding your bin/myapp

Using Configuration Service

require 'rubygems'
require 'carioca'

registry = Carioca::Services::Registry.init :file => 'config/myservices.registry'
config = registry.start_service :name => 'configuration'
config.setings.db = { :name => 'mydb' }
config.settings.db.host = "myhost" 
config.settings.db.port = "4545" 
config.settings.email = "my@email.com" 
config.save!

Using Logger Service

logger is automatically loaded with Carioca, loading registry with :debug => true, let you see the Carioca traces.

require 'rubygems'
require 'carioca'

registry = Carioca::Services::Registry.init :file => 'config/myservices.registry' :debug => true
log = registry.get_service :name => 'logger'
log.info('myapp') {'my message' }

Creating and using your own service

before create your own service :

 $ mkdir services

Services, must be a class, if not do a wrapper
edit services/myservice.rb

  class MyService
    def initialize
    end

    def test(arg = nil)
      return 'OK'
    end
  end
end

You could use the #service_register API (See spec for all details)
but, you could write it directly in YAML in your config/myservices.registry :
add the following lines :

...
myservice:
  :type: :file
  :resource: services/myservice.rb
  :description: a test service
  :service: MyServices
...

So in your app :

require 'rubygems'
require 'carioca'

registry = Carioca::Services::Registry.init :file => 'config/myservices.registry'
service = registry.start_service :name => 'myservice'
service.test('titi')

Using Debug in multiple service instance

in your app, for debug you could use the Proxy Debug (you need to run Carioca Registry in debug mode ) :
(Using "debug_", you create an instance of service debug, so with this syntaxe you could create multiple services instances, with different parameters calling.)

require 'rubygems'
require 'carioca'

registry = Carioca::Services::Registry.init :file => 'config/myservices.registry' :debug => true
proxy1  = registry.get_service :name => 'debug_myservice', :params => {:service => 'myservice'}
proxy1.test('titi')

see the log /tmp/log.file :

D, [2013-03-23T18:20:39.839826 #76641] DEBUG -- ProxyDebug: BEGIN CALL for mapped service myservice
D, [2013-03-23T18:20:39.839875 #76641] DEBUG -- ProxyDebug: called: test
D, [2013-03-23T18:20:39.839920 #76641] DEBUG -- ProxyDebug: args : titi
D, [2013-03-23T18:20:39.839970 #76641] DEBUG -- ProxyDebug: => returned: OK
D, [2013-03-23T18:20:39.840014 #76641] DEBUG -- ProxyDebug: END CALL

Using Gem for a service

For exemple install uuid gem :

  $ gem ins uuid

add to your YAML config config/myservices.registry :

  uuid:
    :type: :gem
    :resource: uuid
    :description: a Rubygems called uuid to build UUID ids.
    :service: UUID

in your app :

  require 'rubygems'
  require 'carioca'

  registry = Carioca::Services::Registry.init :file => 'config/myservices.registry' :debug => true
  uuid  = registry.get_service :name => 'uuid'
  uuid.generate

Copyright

carioca (c) 2012-2013 Romain GEORGES <romain@ultragreen.net> for Ultragreen Software