Class: Carioca::Services::Registry

Inherits:
Object
  • Object
show all
Includes:
PrivateMethodsCariocaServicesRegistry
Defined in:
lib/carioca.rb

Overview

Note:

this class is a Singleton Class to instanciate do not use new (initializer), but : Carioca::Services::Registry.init options

class Registry

This class provide the Registry manager for Carioca

Examples:

Complete usage

require 'rubygems'
require 'carioca'  
registry = Carioca::Services::Registry.init 
registry = Carioca::Services::Registry.init :file => 'myservices.registry'
registry = Carioca::Services::Registry.init :file => 'myservices.registry', :debug => true

Constant Summary collapse

@@inst = 
nil

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from PrivateMethodsCariocaServicesRegistry

#get_ring, #initialize, #instanciate_service, #kill_distributed_service, #kill_service, #require_service, #scan_instance_suffix, #shutdown_ring_if_empty, #verify_requires_dependancies

Instance Attribute Details

#debug ⇒ Object

Examples:

registry = Carioca::Services::Registry.init
p registry.debug


103
104
105
 
# File 'lib/carioca.rb', line 103

def debug
  @debug
end

#list ⇒ Object (readonly)

(come from file and explicitly registered services)

Examples:

registry = Carioca::Services::Registry.init
p registry.list


91
92
93
 
# File 'lib/carioca.rb', line 91

def list
  @list
end

#loaded_services ⇒ Object (readonly)

Examples:

registry = Carioca::Services::Registry.init
p registry.loaded_services # you should see the logger service Hash definition


97
98
99
 
# File 'lib/carioca.rb', line 97

def loaded_services
  @loaded_services
end

#name ⇒ Object

Note:

default value is ‘Carioca’

Examples:

registry = Carioca::Services::Registry.init
p registry.name
registry.name = 'Agent'


111
112
113
 
# File 'lib/carioca.rb', line 111

def name
  @name
end

#registry_filename ⇒ Object

(come from file and explicitly registered services)

Examples:

read

registry = Carioca::Services::Registry.init
p registry.registry_filename

write

registry = Carioca::Services::Registry.init
p registry.registry_filename = '/tmp/test.file'


84
85
86
 
# File 'lib/carioca.rb', line 84

def registry_filename
  @registry_filename
end

Class Method Details

.init(_options = {}) ⇒ Carioca::Services::Registry

Singleton constructor for Registry

Examples:

usage

registry = Carioca::Services::Registry.init # or  
registry = Carioca::Services::Registry.init :file => 'myservices.registry' # or
registry = Carioca::Services::Registry.init :file => 'myservices.registry', :debug => true

Parameters:

  • _options (Hash) (defaults to: {}) —

    the options, keys are symbols

Options Hash (_options):

  • :file (String) —

    The path of your registry YAML definition (see YAML registry format)

  • :debug (TrueClass, FalseClass) —

    Boolean activation/deactiviation of the carioca debug mode (log traces)

Returns:



68
69
70
71
72
73
74
 
# File 'lib/carioca.rb', line 68

def Registry.init(_options = {})
  options = Methodic::get_options(_options)
  options.specify_defaults_values :file => './services.registry', :debug => false, :name => 'Carioca'
  options.merge
  @@inst = new(options) if @@inst.nil?
  return @@inst
end

Instance Method Details

#close ⇒ TrueClass, FalseClass

Note:

the garbage method hook is call if defined, for each service

close the registry (finalizer)

* stop all the services 
* kill logger
* call private kill_service for each

Returns:

  • (TrueClass, FalseClass) —

    true if registry closed successfully



280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/carioca.rb', line 280

def close
  @log.debug('Carioca') { "closing Registry ..." }
  options = Hash::new
  @loaded_services.keys.each do |service|
    options[:name] = service
    options = scan_instance_suffix(options)
    next if options[:name] == 'logger' 
    kill_distributed_service :name => options[:name], :preserve => true if @list[options[:shortname]][:distributed]
    kill_service options unless @list[options[:shortname]][:distributed]
  end
  @log.debug('Carioca') { "Registry services closed, logger will be closed asynchronously" }
  kill_service :name => 'logger'
  return true
end

#discover_builtins ⇒ Object

overload @list (self.list) by adding/reloading the builtins services definition scanned from Carioca gem

alterate @list

Examples:

usage

registry = Carioca::Services::Registry.init :name => '/tmp/empty.file'
registry.discover_builtins
registry.save!


203
204
205
 
# File 'lib/carioca.rb', line 203

def discover_builtins
  @list.merge! Carioca::Services::discover_builtins
end

#load ⇒ Hash Also known as: reload

load the registry file from self.registry_filename

Examples:

usage

registry = Carioca::Services::Registry.init
registry.registry_filename = "./an_other.file"
registry.load #or
registry.reload

Returns:

  • (Hash) —

    @list the list Structure of the loaded registry



302
303
304
 
# File 'lib/carioca.rb', line 302

def load
  @list = YAML.load_file(@registry_filename)
end

#register_service(_options) ⇒ TrueClass, FalseClass

register a new service in registry added to @list

Parameters:

  • _options (Hash) —

    the options hash, key are :symbols

Options Hash (_options):

  • :name (String) —

    the name of the service (required)

  • :resource (String) —

    the resource, must be a gem name, a fullpath filename, a builtin service (required)

  • :type (Symbol) —

    the resource type of the service, must be :gem, :builtin or :file (required)

  • :service (String) —

    the realname of the service class with namespace (eg. ExternalServices::Dummy )

  • :description (String) —

    the description of the service (required)

  • :init_options (Hash) —

    the params of the service, keys are symbols

  • :requires (Array) —

    the list of [String] services name required to load this service

  • :distributed (TruClass|FalseClass) —

    if service must be load as a distributed service

Returns:

  • (TrueClass, FalseClass) —

    true if service is added

Raises:

  • ArgumentError when :type is not in [:gem,:file,:builtin]



168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/carioca.rb', line 168

def register_service(_options)
  options = Methodic.get_options(_options)
  options.specify_classes_of({:name => String, :resource => String, :description => String, :type => Symbol, :service => String }) 
  options.specify_presences_of([:name,:type,:resource,:service])
  cond = Proc::new{|option| if [:gem,:gem_file,:file,:builtin].include? option then true else false end }
  options.specify_condition_for :type => cond
  options.validate!
  _name = _options.delete(:name)
  @list[_name] = _options
  return true
end

#restart_service(_options) ⇒ Object

Note:

Registry and services are Singleton

start or restart (stop=>start) previously started service in @list

Examples:

usage

registry = Carioca::Services::Registry.init 
config = registry.restart_service :name => 'configuration'
config = registry.restart_service :name => 'configuration' # stop and restart the previous services
proxy = subject.restart_service :name => 'debug' , :params => {:service => 'configuration'}

Parameters:

  • _options (Hash) —

    the params, key are symbols

Options Hash (_options):

  • :name (String) —

    the name of the service

  • :params (Hash) —

    the params of the service

Returns:

  • (Object) —

    the loaded service class instance

Raises:

  • (RegistryError) —

    Config Failed, for unconsistant service definition in @list



255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/carioca.rb', line 255

def restart_service(_options)
  options = Methodic.get_options(_options)
  options.specify_classes_of :name => String
  options.specify_presences_of [:name]
  options.validate!
  options = scan_instance_suffix(options)
  dist = (@list[options[:shortname]][:distributed].nil?)? false : @list[options[:shortname]][:distributed]
  if dist and @loaded_services.include? options[:name] then
    @log.debug('Carioca') { "Restarting distributed service #{options[:name]}"} if @log
    kill_distributed_service options
  elsif @loaded_services.include? options[:name] then
    @log.debug('Carioca') { "Restarting service #{options[:name]}"} if @log
    kill_service options     
  end    
  verify_requires_dependancies(options)
  require_service(options)
  return instanciate_service(options)
end

#save! ⇒ TruaClass, FalseClass

save the registry file in self.registry_filename

Examples:

usage

registry = Carioca::Services::Registry.init :file => './empty.file' 
registry.discover_builtins
registry.unregister_service :name => 'configuration'
registry.save!

Returns:

  • (TruaClass, FalseClass) —

    true if the file is saved



214
215
216
217
218
219
220
 
# File 'lib/carioca.rb', line 214

def save!
  res = false
  File.open(@registry_filename, "w") do |f|
    res = true if f.write(@list.to_yaml)
  end
  return res
end

#start_service(_options) ⇒ Object Also known as: get_service

start or get e previously started service in @list

Examples:

usage

registry = Carioca::Services::Registry.init 
config = registry.start_service :name => 'configuration'
proxy = subject.start_service :name => 'debug' , :params => {:service => 'configuration'}

Parameters:

  • _options (Hash) —

    the params, key are symbols

Options Hash (_options):

  • :name (String) —

    the name of the service

  • :params (Hash) —

    the params of the service

Returns:

  • (Object) —

    the loaded service class instance

Raises:

  • (RegistryError) —

    Config Failed, for unconsistant service definition in @list



232
233
234
235
236
237
238
239
240
 
# File 'lib/carioca.rb', line 232

def start_service(_options)
  options = Methodic.get_options(_options)
  options.specify_classes_of :name => String
  options.specify_presences_of([:name])
  options.validate!
  @log.debug('Carioca') { "getting service #{options[:name]}"} if @log
  self.restart_service(options) unless @loaded_services.include? options[:name] 
  return @loaded_services[options[:name]]
end

#stop_service(_options) ⇒ TruaClass, FalseClass

Note:

log if debug mode

stop a service, if loaded and different to logger

Examples:

usage

registry = Carioca::Services::Registry.init 
registry.start_service :name => 'configuration'
registry.stop_service :name => 'configuration'
#=> return true
registry.stop_service :name => 'configuration'
#=> return false
registry.stop_service :name => 'logger'
#=> return false

Parameters:

  • _options (Hash) —

    the options, keys are symbols

Options Hash (_options):

  • :name (String) —

    The name of the service to stop

Returns:

  • (TruaClass, FalseClass) —

    true if service effectivly stopped, false if not, or :name == ‘logger’



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/carioca.rb', line 138

def stop_service(_options)
  options = Methodic.get_options(_options)
  options.specify_class_of :name => String
  options.specify_presence_of([:name])
  options.validate!
  @log.debug('Carioca') { "Service logger can't be unloaded" } if @log and options[:name] == 'logger'
  return false if options[:name] == 'logger'
  if @loaded_services.include?(options[:name]) then        
    options = scan_instance_suffix(options)
    return kill_distributed_service options if @list[options[:shortname]][:distributed]
    return kill_service options
  else
    @log.debug('Carioca') { "Service #{options[:name]} not loaded" } if @log
    return false          
  end
end

#unregister_service(_options = {}) ⇒ TrueClass, FalseClass

unregister a service in registry removed from @list

Parameters:

  • _options (Hash) (defaults to: {}) —

    the options hash, key are :symbols

Options Hash (_options):

  • :name (String) —

    the name of the service (required)

Returns:

  • (TrueClass, FalseClass)

Raises:

  • (RegistryError) —

    if try to unregister logger

  • (registryerror) —

    if try to unregister a loaded service



186
187
188
189
190
191
192
193
194
195
 
# File 'lib/carioca.rb', line 186

def unregister_service(_options = {})
  options = Methodic.get_options(_options)
  options.specify_class_of :name => String
  options.specify_presence_of :name
  options.validate!
  raise RegistryError::new("FONDATION : Can't unregistered the logger service" ) if options[:name] == 'logger'
  raise RegistryError::new("Can't unregistered a loaded service" ) if @loaded_services.include?(options[:name])
  @list.delete(options[:name])
  return true
end