Class: XenApi::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/xenapi/client.rb

Overview

This class permits the invocation of XMLRPC API calls through a ruby-like interface

client = XenApi::Client.new('http://xenapi.test')
client.('root', 'password')
client.VM.get_all

Authenticating with the API

Authentication with the API takes place through the API session class, usually using the login_with_password method. The Client handles this method specially to enable it to retain the session identifier to pass to invoked methods and perform reauthentication should the session become stale.

client = XenApi::Client.new('http://xenapi.test')
client.('root', 'password')

It is worth noting that only login* matching methods are specially passed through to the session class.

Running code after API login

The Client provides the ability for running code after the client has successfully authenticated with the API. This is useful for either logging authentication or for registering for certain information from the API.

The best example of this is when needing to make use of the Xen API event class for asynchronous event handling. To use the API event class you first have to register your interest in a specific set of event types.

client = XenApi::Client.new('http://xenapi.test')
client. do |c|
  c.event.register %w(vm) # register for 'vm' events
end

Asynchronous Methods

To call asynchronous methods on the Xen XMLRPC API you first call Async on the Client instance followed by the normal method name. For example:

client = XenApi::Client.new('http://xenapi.test')
client.('root', 'password')
client.Async.VM.get_all
client.async.VM.get_all

Calling either Async or async will work as the capitalised form will always be sent when calling a method asynchronously.

Defined Under Namespace

Classes: LoginRequired, ResponseMissingErrorDescriptionField, ResponseMissingStatusField, ResponseMissingValueField, SessionInvalid

Instance Method Summary collapse

Constructor Details

#initialize(uri, timeout = 10) ⇒ Client

Returns a new instance of Client.

Parameters:

  • uri (String) —

    URL to the Xen API endpoint

  • timeout (Integer) (defaults to: 10) —

    Maximum number of seconds to wait for an API response



98
99
100
101
102
 
# File 'lib/xenapi/client.rb', line 98

def initialize(uri, timeout = 10)
  @timeout = timeout
  @uri = URI.parse(uri)
  @uri.path = '/' if @uri.path == ''
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(meth, *args) ⇒ true, ...

Note:

meth names are not validated

Handle API method calls.

If the method called starts with login then the method is assumed to be part of the session namespace and will be called directly. For example login_with_password

client = XenApi::Client.new('http://xenapi.test/')
client.login_with_password('root', 'password)

If the method called is async then an AsyncDispatcher will be created to handle the asynchronous API method call.

client = XenApi::Client.new('http://xenapi.test/')
client.async.host.get_servertime(ref)

The final case will create a Dispatcher to handle the subsequent method call such as.

client = XenApi::Client.new('http://xenapi.test/')
client.host.get_servertime(ref)

Parameters:

  • meth (String, Symbol) —

    Method name

  • args (...) —

    Method args

Returns:



161
162
163
164
165
166
167
168
169
170
 
# File 'lib/xenapi/client.rb', line 161

def method_missing(meth, *args)
  case meth.to_s
  when /^login/
    (meth, *args)
  when /^async/i
    AsyncDispatcher.new(self, :_call)
  else
    Dispatcher.new(self, meth, :_call)
  end
end

Instance Method Details

#after_login {|client| ... } ⇒ Client #after_login ⇒ Client

Returns receiver.

Overloads:

  • #after_login {|client| ... } ⇒ Client
    Note:

    The block will be called whenever the receiver has to authenticate with the XenAPI. This includes the first time the receiver recieves a login_* method call and any time the session becomes invalid.

    Adds a block to be called after successful login to the XenAPI.

    Yields:

    • client

    Yield Parameters:

    • client (optional, Client) —

      Client instance

  • #after_login ⇒ Client

    Calls the created block, this is primarily for internal use only

Returns:



114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/xenapi/client.rb', line 114

def (&block)
  if block
    @after_login = block
  elsif @after_login
    case @after_login.arity
    when 1
      @after_login.call(self)
    else
      @after_login.call
    end
  end
  self
end

#inspect ⇒ Object

See Also:

  • Object#inspect


92
93
94
 
# File 'lib/xenapi/client.rb', line 92

def inspect
  "#<#{self.class} #{@uri}>"
end

#xenapi_session ⇒ String

Returns the current session identifier.

Returns:

  • (String) —

    session identifier



131
132
133
 
# File 'lib/xenapi/client.rb', line 131

def xenapi_session
  @session
end