Inter-App Communication Callback Reference¶

This topic describes the callbacks that are available for inter-app communication.

The following categories of callbacks are provided for inter-app communication:

Configuration Callbacks¶

These callbacks are triggered when a configuration changes.

validate_configuration_change¶

This callback is a synchronous callback.

This callback is called as part of ALTER APPLICATION SET CONFIGURATION VALUE command. This callback lets the app perform additional custom validation on the value provided by the server app. If the callback fails, such as with a syntax error, or if the callback returns and error, the set command fails and the new value is not set.

Signature¶

validate_configuration_change(configuration_name, configuration_value)
Copy

Parameters¶

  • configuration_name: The name of the configuration object.

  • configuration_value: The value provided by the server app.

Return value¶

The callback must return a string in the following JSON format to indicate a validation success or error.

{
  "type": "SUCCESS | ERROR",
  "payload":{
      "error_message": "Error message indicating the validation failure"
  }
}
Copy

If the function returns a type of ERROR, the error message is returned as part of the SQL error message of the SET command. If the function returns a type of SUCCESS, the error message is ignored.

before_configuration_change¶

This callback is a synchronous callback. This callback is called as part of ALTER APPLICATION SET CONFIGURATION VALUE and ALTER APPLICATION UNSET CONFIGURATION commands. This callback lets the app perform further operations based on the configuration value set. The value passed into the callback is null for the ALTER APPLICATION UNSET CONFIGURATION command.

Signature¶

before_configuration_change(configuration_name, configuration_value)
Copy

Parameters¶

  • configuration_name: The name of the configuration object.

  • configuration_value: The value provided by the server app.

Return value¶

The return value of the callback is ignored.

after_configuration_change¶

This callback is an asynchronous callback. This callback is called after the ALTER APPLICATION SET CONFIGURATION VALUE and ALTER APPLICATION UNSET CONFIGURATION commands complete. This callback lets the client app be notified when a value is provided by the server app.

Signature¶

after_configuration_change(configuration_name)
Copy

Parameters¶

  • configuration_name: The name of the configuration object.

Retrieving the latest state¶

In the callback, the following code snippet can be used to retrieve the current status and value of the configuration:

session.sql(f"""
  SHOW CONFIGURATIONS ->>
      SELECT "status", "value"
      FROM $1
      WHERE "name" = '{configuration_name}';
  """);
Copy

Connection Callbacks¶

These callbacks are triggered when a connection’s status changes.

after_server_connection_change¶

This callback is an asynchronous callback. This callback is called after the ALTER APPLICATION APPROVE SPECIFICATION or ALTER APPLICATION DECLINE SPECIFICATION command completes. This callback lets the client app be notified when the connection to a server app has been changed, such as when a new connection is established, or the connection to the server is broken.

Signature¶

after_server_connection_change(server_name)
Copy

Parameters¶

  • server_name: The name of the server app for which the connection has been changed.

Retrieving the latest state¶

In the callback, the following code snippet retrieves the current connection status to the server app:

session.sql(f"""
  SHOW SPECIFICATIONS ->>
  SELECT "status"
  FROM $1
  WHERE PARSE_JSON("definition"):"SERVER_APPLICATION"::STRING = '{server_name}';
  """);
Copy

after_client_connection_change¶

This callback is an asynchronous callback. This callback is called after the ALTER APPLICATION APPROVE SPECIFICATION or ALTER APPLICATION DECLINE SPECIFICATION command completes. This callback lets the server app be notified when one of its clients has changed, such as when a new connection is established, or the client drops the connection.

Signature¶

after_client_connection_change(client_name)
Copy

Parameters¶

  • client_name: The name of the client app for which the connection has been changed.

Retrieving the latest state¶

In the callback, the following code snippet can be used to retrieve what roles, if any, have been granted to the client app:

session.sql(f"""
  SHOW GRANTS TO APPLICATION {client_name} ->>
  SELECT "name"
  FROM $1
  WHERE "granted_on" = 'APPLICATION_ROLE'
      AND STARTSWITH("name", CURRENT_DATABASE())
  """);
Copy

Specification Callbacks¶

These callbacks are triggered when a connection specification or app version changes.

  • after_server_version_change

  • after_specification_change

after_server_version_change¶

This callback is an asynchronous callback. This callback is called after the server app’s version or patch number changes. This lets the client app react to the upgrade or downgrade.

Signature¶

after_server_version_change(server_name)
Copy

Parameters¶

  • server_name: The name of the server app for which the version has changed.

Retrieving the latest state¶

In the callback, the following code snippet can be used to retrieve the current version of the server app:

session.sql(f"""
  SHOW APPLICATIONS ->>
  SELECT "version", "patch"
  FROM $1
  WHERE "name" = {server_name}
  """);
Copy

after_specification_change¶

This callback is an asynchronous callback. This callback is called after the ALTER APPLICATION APPROVE SPECIFICATION or ALTER APPLICATION DECLINE SPECIFICATION commands complete. This callback lets the server app be notified when a new specification has been created or updated.

For inter-app communication, this callback replaces the functionality of the specification_action callback. You can only specify one of after_specification_change or specification_action in the manifest file. For information about the specification_action callback, see Using callback functions with app specifications.

Signature¶

after_specification_change(spec_name)
Copy

Parameters¶

  • spec_name: The name of the application specification that has been approved or declined.

Retrieving the latest state¶

In the callback, the following code snippet can be used to retrieve the current status of the specification:

session.sql(f"""
  SHOW SPECIFICATIONS ->>
      SELECT "status"
      FROM $1
      WHERE "name" = '{spec_name}';
  """);
Copy
Language: English