Class: UU::OS::CMD::CommandClient

Inherits:
Object
  • Object
show all
Defined in:
uu_os_cmd-2.2.5/lib/uu/os/cmd/command_client.rb

Overview

CommandClient is used for execution of command requests.

Examples:

Basic usage:

client = UU::OS::CMD::CommandClient.new('cds-bookcase', session)
attributes = client.exec('Bookcase/getAttributes', bookcase_uri)

Constant Summary

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (CommandClient) initialize(app_url_code, session, options = nil)

Creates new instance of CommandClient for given application (or application module).

Parameters:

  • app_url_code (String) —

    Application URL code in format “vendor-app[-module]”.

  • session (Object) —

    Object providing execution environment data. All commands invoked from this instance will use data provided by this session object (even if other session, e.g. session containing other authentication, data was meanwhile created). For details of session object requirements see documentation of method handle_session.

  • options (Hash) (defaults to: nil) —

    Additional configuration options.

Options Hash (options):

  • :base_url (String) —

    Base URL common for invocation of all commands (defaults to cmd.plus4u.net).

  • :validate_ssl (TrueClass, FalseClass) —

    Flag if SSL communication should be validated (defaults to true which requires valid server certificate).

  • :ssl_version (String) —

    SSL version to be used for communication (defaults to value provided by particular version of Ruby).

  • :ssl_cert_store (String) —

    Path to alternate SSL certificate store to be used instead of default one.

  • :reduce_network_usage (TrueClass, FalseClass) —

    Flag if network usage should be optimized in tradeoff for reasonable CPU/memory performance hit (defaults to true).

  • :default_action (Symbol, String) —

    Default use case action to be used with generic command invocation (invocation using invoke method, defaults to exec).

  • :command_handlers (#handle_request, #handle_response, #handle_error, #handle_redirect, Array<#handle_request, #handle_response, #handle_error, #handle_redirect>) —

    Any object (or list of objects) that responds to handle_request, handle_response, handle_error or handle_redirect. In case this parameter is defined, given handlers are used additionally to default handler (which is always invoked last). In case of list, order of handler invocation is same as order in list.

  • :session_handler (#handle_session) —

    Any object that responds to method handle_session. In case this parameter is defined, given object is used as session handler instead of default one.

  • :connect_timeout (Fixnum) —

    Timeout for remote connection initialization in seconds (defaults to 1 second, use 0 for infinite timeout).

  • :request_timeout (Fixnum) —

    Request timeout in seconds (defaults to 30 seconds, use 0 for infinite timeout).

  • :append_routing_data (TrueClass, FalseClass) —

    If set to true (default value) routing data (in particular territory identification) are added to request path.



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'uu_os_cmd-2.2.5/lib/uu/os/cmd/command_client.rb', line 117

def initialize(app_url_code, session, options = nil)
  use_legacy_config = get_param(options, :use_legacy_config) || false
  @app_url_code = app_url_code
  @session = session
  @command_handlers = DEFAULT_COMMAND_HANDLERS.dup
  command_handlers = get_param(options, :command_handlers, :classes)
  @command_handlers.unshift(*command_handlers) if command_handlers
  session_handler = get_param(options, :session_handler, :classes)
  if session_handler.respond_to?:handle_session
    @session_handler = session_handler
  else
    @session_handler = DEFAULT_SESSION_HANDLER
  end
  @default_action = get_param(options, :default_action, :string)
  @default_action = DEFAULT_ACTION if @default_action.nil?
  @main_object_uri_parameter_name = get_param(options, :main_object_uri_parameter_name, :string)
  @main_object_uri_parameter_name = DEFAULT_MAIN_OBJECT_URI_PARAMETER_NAME if @main_object_uri_parameter_name.nil?
  @parameters_parameter_name = get_param(options, :parameters_parameter_name, :string)
  @parameters_parameter_name = DEFAULT_PARAMETERS_PARAMETER_NAME if @parameters_parameter_name.nil?
  @append_routing_data = get_param(options, :append_routing_data, :boolean)
  @append_routing_data = true if @append_routing_data.nil?
  # emergency break, now all requests use request_async method on http client
  # if any problem arises, set invoke_asynchronous_request to false
  @enable_request_streaming = get_param(options, :enable_request_streaming, :boolean)
  @enable_request_streaming = true if @enable_request_streaming.nil?
  # Prepare instance of HTTPClient which is used for communication
  if use_legacy_config
    base_url = get_param(options, :base_url, :string, :server-url')
    validate_ssl = get_param(options, :validate_ssl, :boolean, :validate-server-cert')
    ssl_version = get_param(options, :ssl_version, :string, :server-ssl-version')
  else
    base_url = get_param(options, :base_url, :string)
    validate_ssl = get_param(options, :validate_ssl, :boolean)
    ssl_version = get_param(options, :ssl_version, :string)
  end
  base_url ||= get_param(options, :default_base_url) || DEFAULT_BASE_URL
  @http_client = UU::OS::HTTP::HTTPClient.new(base_url)
  # Reconfigure default headers
  @http_client.set_header(:accept, 'application/json', '*/*')
  @http_client.set_header(:content_type, 'application/json')
  # Reconfigure client based on options parameter
  @http_client.tranparent_gzip_decompression = get_param(options, :reduce_network_usage, :boolean)
  @http_client.ssl_validation = validate_ssl
  @http_client.ssl_version = ssl_version
  @http_client.ssl_cert_store = get_param(options, :ssl_cert_store, :string)
  @http_client.connect_timeout = get_param(options, :connect_timeout, :number)
  @http_client.request_timeout = get_param(options, :request_timeout, :number)
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

- (Object) method_missing(method, *args, &block) (private)

Transforms call of unknown method to specific action.



371
372
373
374
375
376
377
378
 
# File 'uu_os_cmd-2.2.5/lib/uu/os/cmd/command_client.rb', line 371

def method_missing(method, *args, &block) #:nodoc:
  # Command invocation must have method, entity and optional parameters
  if (args.size < 2) || (args.size > 3)
    return super
  else
    return __invoke(args[0], to_camel_case(method), args[1], args[2])
  end
end

Class Method Details

+ (void) load_configuration(configuration)

This method returns an undefined value.

Loads external configuration to be used by all instances of command client. This configuration has priority over implicit default values, however can be overridden by command client initialization options. Configuration is "path based", therefore it is possible to globally reconfigure behavior only for certain modules or applications, leaving others with default values. Repeated invocation of method does not overwrite previously loaded values, but configurations are merged. Therefore it is possible for each module to load its configuration (as long as they are using unique path).

Configuration keys are expected in format <dot.separated.path>.<option> where path is based on application module URL path (e.g. uu.os.artifact or cds.issues) and option is one of initialization options.

  • String - Path to configuration file in properties format.

  • #read - Instance of existing IO (e.g. File) pointing to data in properties format.

  • Hash - Configuration in plain key-value format.

Parameters:

  • configuration (String, #read, Hash) —

    Possible values are:



215
216
217
 
# File 'uu_os_cmd-2.2.5/lib/uu/os/cmd/command_client.rb', line 215

def self.load_configuration(configuration)
  EXTERNAL_CONFIGURATION.merge!(configuration)
end

Instance Method Details

- (Object, ...) invoke(cmd_url_path, uu_uri, parameters = nil)

Invokes command with given parameters. When using this method, default use case action is invoked (which may be configured via options parameter in CommandClient constructor and defaults to exec).

Parameters:

  • cmd_url_path (String) —

    URL path of command to be invoked

  • uu_uri (URI, String) —

    URI of main object (object to be processed by invoked command) given either as plain string or instance of URI (any other type is transformed using #to_s method).

  • parameters (Hash) (defaults to: nil) —

    Additional execution parameters.

Options Hash (parameters):

  • :parameters (Hash, IO, String) —

    Actual method parameters (typically represented as DTO). Note that command data interchange protocol uses “camelCase” for attribute names. In case “snake_case” attributes are given in Hash parameter, they might be ignored by server (no transformation of attribute names is done by CommandClient). Particular allowed type of parameter depends on additional options and command type:

    • POST commands

      TODO hash contains binary value -> multipart file upload

      • no options - Hash is transformed to JSON. String or IO are send without transformation (but expected content is valid JSON representing serialized Hash). TODO remove binary_uplad flag (or use it to be able to upload single instance of IO without creating instance of binary value?)

      • :binary_upload - Hash containing at least :data attribute (Attribute may contain String or IO and is always send as last part). Additionally Hash may contain name, contentType and size parameters. If not set, these parameters are derived from data parameter where possible. TODO contains binary value -> multipart is implicitly used

      • :multipart_upload - Hash in plain key-value structure (any nested structure is transformed to JSON)

    • GET commands

      • Only allowed type is Hash which is transformed to query parameters (nested structures are transformed to JSON, however it is strongly recommended to not use them because of limited length of request URL).

  • :stream_response (TrueClass, FalseClass, nil) —

    Flag if response should be streamed - returned as IO (defaults to false, should be set to true in case response might be bigger than 5MB).

  • :content_type (String) —

    Content type of request (defaults to application/json or multipart/form-data see description of :parameters for details).

  • :accept (String, nil) —

    Requested content type of response (defaults to application/json).

  • :invocation_method (Symbol, String, nil) —

    Type of command invocation (defaults to POST).

  • :async_invocation (TrueClass, FalseClass, nil) —

    Flag if command should be invoked asynchronously on client. Note that this does not mean invocation of asynchronous command! Result is returned as instance of Future. (defaults to false)

  • :raw_response (TrueClass, FalseClass, nil) —

    Flag if CommandResult object should be returned instead of actual processed result (defaults to false, if set to true CommandResult is returned also from asynchronous invocation).

  • :command_handlers (#handle_request, #handle_response, #handle_error, #handle_redirect, Array<#handle_request, #handle_response, #handle_error, #handle_redirect>, nil) —

    Any object (or list of objects) that responds to handle_request, handle_response, handle_error or handle_redirect. In case this parameter is defined, given handlers are used additionally and prior to handlers declared in CommandClient constructor. In case of list, order of handler invocation is same as order in list.

  • :binary_upload (TrueClass, FalseClass, nil) —

    Flag if binary value is being send as command parameter (defaults to false).

  • :multipart_upload (TrueClass, FalseClass, nil) —

    Flag if parameters should be transformed into multipart message (defaults to false).

  • :callback (Object, nil) —

    Object containing parameters for callback (defines operation to be invoked once asynchronous command is finished). Callbacks are supported only for server side where valid callback parameters to be used can be obtained via method ExecutionContext#prepare_callback.

  • :... (Object, nil) —

    Any given options are not modified. Therefore custom command handler can define additional options to be used for processing command request or command response.

Returns:

  • (Object, UU::OS::CMD::CommandResult, UU::OS::Lang::Future) —

    Command result. Actual type of returned value depends on given options and also on set of used command handlers. Note that in case of Hash result value, all attribute names will be in “camelCase” since this notation is by default used in command data interchange protocol (and no transformation of attribute names is done by CommandClient).



275
276
277
 
# File 'uu_os_cmd-2.2.5/lib/uu/os/cmd/command_client.rb', line 275

def invoke(cmd_url_path, uu_uri, parameters = nil)
  return __invoke(cmd_url_path, @default_action, uu_uri, parameters)
end