Registering a UDX in an Extension Library

This topic provides information on registering a new user-defined extension (UDX) in C++ environments.

Registering C++ UDXs

The following instructions show you how to register the UDF by specifying the function's metadata in JSON format. You can supply the registration information in the same CPP file that you created to define the function, or you can create a separate CPP file for the registration metadata. You can also register multiple functions in the same CPP file.

To register a UDF, add the following extern "C" void register_extensions (MetaData& md) declaration to the CPP file that defines the UDF or a separate CPP file.

Open register.cpp in a separate window

extern "C" void register_extensions(MetaData& md)
{
  md.json_metadata = R"(
  {
    "name"          : "UDX_lib_name",
    "language"      : "c++",
    "version"       : "version",
    "description"   : "UDX_lib_description",
    "author"        : "author_or_company",
    "copyright"     : "copyright_statement",
    "contents"      : [
      {
      "name"          : "function_URI",
      "type"          : "function",
      "signature"     : " udx_functionName",
      "arguments"     : ["arg1_type","arg2_type"],
      "results"       : "result_type",
      "description"   : "function_description"
      }
     ]
    }
  )";
}

The properties at the top of the declaration describe the overall extension library. The properties in the contents array describe the UDF to register. To describe multiple UDFs in a single CPP file, include multiple contents arrays, for example:

extern "C" void register_extensions(MetaData& md)
{
  md.json_metadata = R"(
  {
    "name"          : "UDX_lib_name",
    "language"      : "c++",
    "version"       : "version",
    "description"   : "UDX_lib_description",
    "author"        : "author_or_company",
    "copyright"     : "copyright_statement",
    "contents"      : [
      {
      "name"          : "function_URI_1",
      "type"          : "function",
      "signature"     : " udx_functionName_1",
      "arguments"     : ["arg1_type","arg2_type"],
      "results"       : "result_type",
      "description"   : "function_description"
      },
      {
      "name"          : "function_URI_2",
      "type"          : "function",
      "signature"     : " udx_functionName_2",
      "arguments"     : ["arg1_type","arg2_type"],
      "results"       : "result_type",
      "description"   : "function_description"
      }
     ]
    }
  )";
}

The table below defines each property that is specified for each extension in an extension library file:

Property	Description
name	Required. Property that specifies the globally unique name to use for this extension library. The name must be unique within AnzoGraph DB. For example: "CSI C++ Extension Functions".
language	Required. Property that specifies the language for the library. The value must be "c++" or "jvm". In this case, the value "c++" is specified.
version	Required. Property that specifies the version of the library in Semantic Versioning format: major.minor.patch. The first digit is required and specifies the major version number. The second digit is optional and specifies the minor version number, and the third digit is optional and specifies the patch number. For example: "1.0.0".
description	Optional. Property that provides a description of the extension library. For example: "An extension library implemented in C++".
author	Optional. Property that specifies the author or company name. For example: "abc@company.com".
copyright	Optional. Property that provides a copyright statement to use for the library. For example: "Copyright © Cambridge Semantics. All rights reserved."
contents	Required. Array that registers one or more extensions that are included in this library. When registering multiple extension in the same library, repeat the contents array for each extension.

For each extension, the contents array specifies a number of generic properties pertaining to the extension, plus some additional properties based on the UDX type (see UDX Examples). The following table lists the common properties specified in the contents array for extensions:

Property	Description
name	Required. Property that specifies the globally unique URI used to identify this extension. The URI must be unique in AnzoGraph DB and is referenced in SPARQL queries to invoke this extension. Cambridge Semantics recommends that you use a format such as http://mycompany.com/grouping/etc#function_name. For example: "http://cambridgesemantics.com/udx/function#concat" If you included the error handling azg_throw macro in the extension definition, make sure that this URI value matches the URI in azg_throw.
type	Required. Property that specifies the type of this extension. The value must be "function", "aggregate", or "service".
signature	Required. Property that specifies the globally unique C language identifier for the extension. The value must be udx_ followed by the extension name, as specified as the extern "C" factory extension name used to instantiate the extension. For example, Cambridge Semantics recommends names of the form: "udx_mycompany_mylibraryname_myextension_name".
arguments	Required. Property that lists the JSON type for each of the extension's input arguments. Specify the JSON type that corresponds to the enum type that you chose for each of the arguments when you implemented the interface. Refer to UDX Data Types for a list of the JSON types. For example: ["double","String"].
results	Required. Property that specifies the JSON type for the extension's return value. For example: "double".
description	Optional. Property that provides a description of the extension. For example: "A function that concatenates string values."

Once a UDX is defined and registered, follow the instructions in Compiling UDX Source Files to create a shared object file for loading to AnzoGraph DB.