Python Plugin Callbacks

These Callbacks are registered in the Server. They can be called from Python Plugins and are executed in the Server.

The Callbacks belong to different Contexts and can only be called in the correct Context.

Contexts

Base

The general context from which most of the callback methods are executed.

The Base context contains information about the server configuration, the current session of the user that caused the callback, or e.g. information about the exporter, when an export_produce callback is executed. When objects are updated or deleted, the context contains information about the object data.

This context allows to perform tasks with the same session as the user, including performing elasticsearch requests or Postgres queries.

Process

Process plugins, that run parallel to the server, get their own process context. It contains no session information.

This context allows to perform tasks without a session, or with a session that was created for the plugin, including performing elasticsearch requests or Postgres queries.

Session

Registered Callbacks

Wrapper Classes

• EasydbException
• Errors
• EasydbContext
• EasydbProcessContext
• EasydbServerContext
• EasydbConnection
• EasydbConnectionCursor
• EasydbCursor
• EasydbLogger

EasydbException

Constructor:

__init__(e_type, message)

get_code

get_code()

Returns the value of the key 'code' of the parsed message.

get_parameter

get_parameter(parameter)

Returns the value of the key 'parameters.{0}'.format(parameter) of the parsed message.

Parameters:

Errors

The Wrapper methods can raise different Errors that correspond to the Errors in the Server. All of them extend the Python Exception EasydbError:

Constructor:

__init__(kind, error_type, description)

The Exception contains two additional member variables, that can be accessed be extending classes:

ServerError

Extends EasydbError

Constructor:

__init__(type, description, debug_info)

Values:

GenericServerError

Extends ServerError

Constructor:

__init__(type, description [, debug_info])

Values:

APIError

Extends EasydbError

Constructor:

__init__(type, description)

Values:

PositionalParameterExpectedError

Extends APIError

Constructor:

__init__(example)

Values:

TypeMismatchError

Extends APIError

Constructor:

__init__(what, expected_type)

Values:

InvalidValueError

Extends APIError

Constructor:

__init__(varname, value [, valid_range])

Values:

InvalidRequestMethodError

Extends APIError

Constructor:

__init__(request_method)

Values:

AttributeExpectedError

Extends APIError

Constructor:

__init__(attribute)

Values:

UserError

Extends EasydbError

Constructor:

__init__(type [, parameters])

Values:

NoSystemRightError

Extends UserError

Constructor:

__init__(right [, extra_info])

Values:

NotFoundError

Extends UserError

Constructor:

__init__(type, id)

Values:

ObjectNotFoundError

Extends UserError

Constructor:

__init__(objecttype, id)

Values:

EasydbContext

call

call(method [, parameters [, returns_json]])

Executes the method that is registered under the given name. The Parameters are given as the String representation of a JSON-Object. Most of the following methods are convenient helper methods, which use this method and build the Parameter-Object from their parameters.

Example Usage:

call ('dbapi_export', {'mask': '_all_fields', 'ids': [9, 24]})

Parameters:

check_system_right

check_system_right(right [, session])

Checks if the User of the specified Session has the given Right (or if the User is Root). If not, a NoSystemRightError is raised. If no Session is given, the current Session is used.

Parameters:

check_system_right_bool_parameter

check_system_right_bool_parameter(right, parameter [, session])

Checks if the User of the specified Session has the given parameterized Right and if the Right is set to True (or if the User is Root). If not, a NoSystemRightError is raised. If no Session is given, the current Session is used.

Parameters:

create_unique_ids_type

create_unique_ids_type(type)

Uses Callback 'create_unique_ids_type' in Context Base.

Parameters:

dbapi_export

dbapi_export(mask, ids)

Starts an Export of the Objects with the given IDs. See dbapi_export

Uses Callback 'dbapi_export' in Context Base.

Parameters:

delete_unique_id

delete_unique_id(type, unique_id)

Uses Callback 'delete_unique_id' in Context Base.

Parameters:

drop_unique_ids_type

drop_unique_ids_type(type)

Uses Callback 'drop_unique_ids_type' in Context Base.

Parameters:

export_objects_as_xml

export_objects_as_xml(objs, mapping_type, mapping, user_id, language)

Export the given array of JSON Objects as a JSON Object with an array of XML Documents. An XML Mapping Profile is applied.

The result has the following structure:

{
    "documents": [
        "<objects> ... </objects>",
        "<objects> ... </objects>"
    ]
}

Uses Callback 'export_objects_as_xml' in Context Base.

Parameters:

* For information about Metadata Formats and Mappings, see XML Mapping and OAI/PMH Metadata Formats.

export_object_as_xml

export_object_as_xml(obj, mapping_type, mapping, user_id, language)

Export the given JSON Object as an XML Document. An XML Mapping Profile is applied.

The result is a JSON Object with the following structure:

{
    "document": "<objects> ... </objects>"
}

This is a wrapper function which calls export_objects_as_xml using an array with the given object as the single element.

Parameters:

get_collection_json

get_collection_json(collection_id, connection_id)

Returns JSON Object of the requested Collection.

Uses Callback 'get_collection_json' in Context Process.

Parameters:

get_config

get_config([path [, expected]])

Returns a JSON-Representation of the Configuration, or a Subobject if a path is specified. If expected is True and the requested Configuration does not exist, an EasydbException is raised.

Parameters:

Top Level of the result:

{
  "base": {
    ...
  },
  "extensions": {
    ...
  },
  "system": {
    ...
  },
  "defaults": {
    ...
  }
}

get_datamodel

get_datamodel([show_easy_pool_link [, show_has_easy_owning_tables]])

Returns a JSON object with information about the current data model. It contains a list of objects with information about the tables (objecttypes) in the datamodel.

Parameters:

{
  "user": {
    "tables": [
      {
        "name": "table_foo",
        "easy_pool_link": True,
        "has_easy_owning_tables": False
      }
    ]
  }
}

get_db_cursor

get_db_cursor()

Returns an EasydbCursor object.

Uses Callback 'db_cursor' in Context Base.

get_environment_variables

get_environment_variables()

Uses Callback 'get_environment_variables' in Context Session.

get_exporter

get_exporter()

Returns a wrapped PyObject of the current export worker context.

get_instance

get_instance()

Returns a JSON object with information about the current easydb instance. Example:

{
  "api": "1",
  "solution": "Solution Name",
  "name": "0123abcd-1234-cdef-1919-9f8e7d6c5b4a",
  "db-name": "Database Name",
  "eas_produce_md5": "0e1e6a8063793bcbad3d1824b6433199",
  "server_start_time": "1506520840"
}

Uses Callback 'get_instance' in Contexts Base and Process.

get_logger

get_logger(name)

Returns an instance of EasydbLogger with the given name.

Parameters:

Example:

log = easydb_context.get_logger('extension.example_plugin')
log.info('Hello World!')
log.debug('debugging variable i: %03d' % i)

results in the following output in the server log:

[  server][2018-01-02T12:34:56.987654][ 12345][    INFO][...on.example_plugin] Hello World!
[  server][2018-01-02T12:34:56.987654][ 12345][   DEBUG][...on.example_plugin] debugging variable i: 005

get_plugins

get_plugins()

Returns the JSON-Representations of the available Plugins.

get_plugin

get_plugin(name)

Returns the JSON-Representation of the Plugin with the given Name, if it exists in the result of get_plugins().

Parameters:

get_remote_user

get_remote_user()

Returns the value of REMOTE_USER from the result of get_environment_variables(). Raises a GenericServerError if this key is not found.

get_kerberos_user

get_kerberos_user()

Returns the Result of get_remote_user()

get_session

get_session()

Returns the JSON-Representation of the current Session.

Uses Callback 'get_session' in Context Session.

insert_unique_id

insert_unique_id(type, unique_id)

Uses Callback 'insert_unique_id' in Context Base.

Parameters:

ldap_bind

ldap_bind([url [, who [, cred]]])

Parameters:

ldap_search

ldap_search(base, scope [, filterstr [, attrlist [, filter_output]]])

Parameters:

ldap_unbind

ldap_unbind()

next_unique_id

next_unique_id(type)

Uses Callback 'next_unique_id' in Context Base.

Parameters:

next_unique_id_prefixed

next_unique_id_prefixed(type, length, prefix)

Uses Callback 'next_unique_id_prefixed' in Context Base.

Parameters:

search

search(session_type, session_identifier, query [, include_sets [, include_eas_urls]])

Performs a search request to the Elasticsearch Instance of the Server. The search result is returned as a JSON Object. See api/search.

Uses Callback 'search' in Context Base.

Parameters:

sequence_create

sequence_create(name [, minvalue [, maxvalue [, if_exists]]])

Uses Callback 'db_sequence' in Context Base.

Parameters:

sequence_exists

sequence_exists(name)

Uses Callback 'db_sequence' in Context Base.

Parameters:

sequence_nextval

sequence_nextval(name)

Uses Callback 'db_sequence' in Context Base.

Parameters:

update_user_objects

update_user_objects(type, ids)

update_user_objects –> Uses Callback 'update_objects' in Context Base.

Parameters:

EasydbSession

Member Variables:

See types/Session.

EasydbProcessContext

Extends EasydbContext

call

call(method [, parameters [, returns_json]])

Wrapper method for locked call from EasydbContext:

with self.lock:
    return EasydbContext.call(method, parameters, returns_json)

create_session

create_session(connection, user_id)

Returns an EasydbSession instance for the User with the given ID.

Uses Callback 'create_session' in Context Process.

Parameters:

db_connect

db_connect(application_name)

Returns an EasydbConnection instance that represents the connection to the easydb with the given name application_name.

Uses Callback 'db_connect' in Context Process.

Parameters:

dbapi_import

dbapi_import(connection, session, mask, objects [, collection_id])

Uses Callback 'dbapi_import' in Context Process.

Parameters:

get_config

get_config(connection)

Returns a JSON object with the configuration of the given EasydbConnection.

Uses Callback 'get_config' in Context Process.

Parameters:

get_logger

get_logger(name)

Returns an instance of EasydbLogger with the given name.

Parameters:

log_event

log_event(connection, event_type [, event_info])

Helper method to write a log output for this specific connection.

Uses Callback 'log_event' in Context Process.

Parameters:

put_asset_from_file

put_asset_from_file(session, filename, original_filename, mapping_name, mask, objecttype, pool_id)

Uses Callback 'put_asset_from_file' in Context Process.

Parameters:

search

search(connection, session_type, session_identifier, query [, include_sets [, include_eas_urls]])

Performs a search request to the Elasticsearch Instance of the Server using the current connection. The search result is returned as a JSON Object. See api/search.

Uses Callback 'search' in Context Process.

Parameters:

EasydbServerContext

Extends EasydbContext.

register_callback

register_callback(callback_type, callback_parameters)

Register a callback method that can be called from the server.

Parameters:

Example:

easydb_context.register_callback('api', {
  'name': 'config',
  'callback': 'config'
})

name is the name of this callback in the server. To execute the method in the plugin, the server references this name. callback is the name of the python method that is executed for the callback.

EasydbConnection

Constructor

__init__(easydb_context, connection_id)

This Constructor is internally called in the wrapper method db_connect. It should not be called on its own.

open_txn

open_txn()

Opens a new transaction, internally identified by connection_id.

Uses Callback 'db_open_txn' in Context Process.

close

close()

Closes this transaction, internally identified by connection_id.

Uses Callback 'db_close_connection' in Context Process.

abort

abort()

Aborts this transaction, internally identified by connection_id.

Uses Callback 'db_abort' in Context Process.

commit

commit()

Commits this transaction, internally identified by connection_id.

Uses Callback 'db_commit' in Context Process.

cursor

cursor()

Returns an instance of EasydbConnectionCursor for this connection.

EasydbCursor

Using an EasydbCursor instance, PostgreSQL statements can be executed on the database that is connected to the easydb instance.

The following example shows how to execute a SELECT statement and log the result:

# Parameter 'context': instance of EasydbContext
def easydb_cursor_example(context, logger):

    # get the EasydbCursor instance
    cursor = context.get_db_cursor()

    # get some rows of a table
    cursor.execute('SELECT text_a, int_b, bool_c FROM table WHERE int_b IN (1, 2, 3)')
    # the number of rows in the result is saved in cursor.rowcount
    logger.info('Statement returned {0} rows'.format(cursor.rowcount))

    # iterate over the rows
    for i in range(cursor.rowcount):
        # get the current row as a dict
        row = cursor.fetchone()
        # get the content of the columns
        logger.info('Row {0}: text_a: {1}'.format(i, row['text_a']))
        logger.info('Row {0}: int_b: {1}'.format(i, row['int_b']))
        logger.info('Row {0}: bool_c: {1}'.format(i, row['bool_c']))

execute

execute(statement)

Parameters:

fetchone

fetchone()

Fetch the next row from the result. Returns a dict that contains the content of the result row.

The keys of the dictionary are the names of the database columns. The values are represented with a python data type according to the database type. For example:

fetchall

fetchall()

Fetch all rows from the result. Returns a list which contains a dict for each row.

fetchmany

fetchmany([size])

Fetch the next rows from the result. If size is set, fetch this many rows. Returns a list which contains a dict for each row.

Parameters:

commit

commit()

Commit the current Transaction.

abort

abort()

Abort the current Transaction.

EasydbConnectionCursor

Constructor

__init__(connection)

This Constructor is called in the wrapper method cursor.

execute

execute(statement)

Uses Callback 'db_execute' in Context Process.

Parameters:

fetchall

fetchall()

Fetch all rows from the result.

Uses Callback 'db_fetchall' in Context Process.

fetchmany

fetchmany([size])

Fetch the next rows from the result. If size is set, fetch this many rows.

Uses Callback 'db_fetchmany' in Context Process.

Parameters:

fetchone

fetchone()

Fetch the next row from the result.

Uses Callback 'db_fetchone' in Context Process.

EasydbLogger

Prints Log Messages, using the Logger class in the Server. Uses Callback 'log' in Context Base.

The following methods are Wrapper methods for the log levels DEBUG, INFO, WARN, ERROR and print the String message:

debug

debug(message)

info

info(message)

warn

warn(message)

error

error(message)