General services

Our service implementation is collected in valuea_framework.broker, which contains the necessary components to construct services and listen for messages on a RabbitMQ queue (using valuea_framework.connectors.rabbitmq.Consumer.RabbitMQRPCConsumer).

How to use services is described in detail in our examples (1. “Hello world!” Service).

BaseService

This is the default service type from where all other services should inherit, either direct or indirect (subclassing direct descendants). Basically this type of service implements all the default handles needed to fit the framework, such as extendable message validation, execution and message parsing.

ServiceRelational

When using sqlalchemy, this type of service prepares a connection and provides some guidance to return standard objects to the user interface (with object_to_ui).

Using the data from 8. Relational modeling we can output an object using the following example:

services/valuea/samples/get_user_object.json

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"description": "get_user_object",
	"properties": {
		"id": {
			"type": ["int", "null"]
		}
	},
	"required": [
		"id"
	]
}

services/valuea/samples/get_user_object.py

import valuea_framework.broker.ServiceRelational
import model.valuea.sample


class Service(valuea_framework.broker.ServiceRelational):
    def __init__(self, *args, **kwargs):
        super(Service, self).__init__(*args, **kwargs)

    def execute(self):
        msg = self.get_message(True)
        user = None
        if msg.id:
            user = self.rdbms_session.query(model.valuea.sample.User).get(msg.id)
        if not user:
            user = model.valuea.sample.User().load_object_defaults()

        return self.object_to_ui(user)

When execute() is called, this method will try to fetch the requested record [line 13], when not found or an id wasn’t provided we return a default object. This should ensure that we always receive a structure we can interpret in the user interface.

Test it locally using:

run_get_user_object_local.py

#!/usr/bin/env python

import services.valuea.samples.get_user_object

srv = services.valuea.samples.get_user_object.Service()
srv.set_message({'id': 1})
print (srv.execute())

Note

When the model object passed into object_to_ui contains foreign keys or choice fields, these will be converted to lists of items containing all the available and selected options.

ServiceRelationalSearch

This type of service derives from ServiceRelational and contains the default parameters and handles needed for the grid component we use (bootgrid).

services/valuea/samples/search_users.json

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"description": "search_users",
	"properties": {
		"rowCount": {
			"type": "integer"
		},
		"current": {
			"type": "integer"
		},
		"searchPhrase": {},
		"sort": {}
	},
	"required": [
		"rowCount"
	]
}

services/valuea/samples/search_users.py

import valuea_framework.broker.ServiceRelationalSearch
import model.valuea.sample


class Service(valuea_framework.broker.ServiceRelationalSearch):
    __query_fieldnames__ = ['id', 'name']
    __search_fieldnames__ = ['name']

    def get_query(self):
        return self.rdbms_session.query(model.valuea.sample.User).subquery()

    def __init__(self, *args, **kwargs):
        super(Service, self).__init__(*args, **kwargs)

The __query_fieldnames__ and __search_fieldnames__ define the fields returned by the call and get_query() specifies which data should be acquired using this search operation.

To test this locally, use:

run_search_users_local.py

#!/usr/bin/env python

import services.valuea.samples.search_users

srv = services.valuea.samples.search_users.Service()
srv.set_message({'rowCount': 10})
print (srv.execute())

ServiceDistributed

Our distributed service can be used to compute in parallel, a configuration file is needed to setup the communication, similar to:

config/mq.conf

[default]
host=192.168.56.101
username=admin
password=admin
exchange=default_exchange

Where the tag [default] is used to refer to a specific channel setup, which can use a different queue configuration.

The service itself supports two main handles, push_request(endpoint, content) to push messages back to the queue for further processing and fetch_results() to fetch results until all requests are processed or timeouts are reached.

Conceptually this type of service is used as a message coordinator which divides work until all is done.

Tip

When using a distributed service, make sure you either use different queues for the workers to avoid blocking regular services or throttle the number of request pushed at the same time with the service.

ServiceQueueOnly

The queue only service type is available for asynchronous services. Like the ServiceDistributed this type needs the same configuration to identify the target which will receive the asynchronous commands.

A regular workflow for an asynchronous service looks like this:

Where the execute is similar to any other type of service, which should use the queue action to offload the actual command to another worker and return the generated message id back to the user.

Our service might look similar to the following, where we are going to execute the valuea.samples.plusone service asynchronous, if extensive message logging is enabled you should be able to fetch the result although it is not send to any real client.

services/valuea/samples/requeue.py

import valuea_framework.broker


class Service(valuea_framework.broker.ServiceQueueOnly):
    def __init__(self, *args, **kwargs):
        super(Service, self).__init__(*args, **kwargs)

    def execute(self):
        return {'messageid': self.queue('valuea.samples.plusone', {'x': 1})}