API Client Library Generator Guide

General Kaltura and API
[Hide Book Menu]

Mon, 08/17/2009 - 01:04 — Kalturian

Client Library Generator - automatic packaging of client libraries

The Kaltura Server provides a unique way of generating an always updated Kaltura Client Libraries by using an XML based reflection of the system classes.

The updated version can be retrieved at the following URL:
http://www.kaltura.com/api_v3/api_schema.php

By parsing the schema.xml file it is possible to construct the complete structure of the objects in the system.
A generic template to parse the schema file was created to ease the process of creating new parsers.

The TemplateClientGenerator is a basic template for creating a custom client library generator, by providing the following:

High-level parsing of class types: Enums, Objects and Services (implementated generate() function).
Template parsing functions to be override or replaced by actual implementation to create the client library of the target programming language.

Schema structure

The schema is divided to three main sections:

Enums - Constants and Types defined and used by the system.
Classes - Objects (VO - Value Objects) defined and used by the system.
Services - The Services and Actions defined and exposed by the system API to manipulate the Objects.

Every node defines a respective part of the system (whether enum, class or service) and provides the following information:

Enums - define name and value of the constant properties of the enum class.
Classes - define name, variable type (string, int, etc.), if the property is readOnly (read) or insertOnly (write) and description of the class and it's uses.
Services -define a list of actions available, the parameters sent required by the action, the service and actions description and uses.

Creating a client library generator

To create your own customized Automatic Kaltura API Client Library, download the latest TemplateClientGenerator project.
The TemplateClientGenerator project include the following files:

ClientGeneratorFromXml.php - Abstract class extended by the TemplateClientGenerator, provides base helper functions.
generate_client.php - Wrapper script to run the generator and test the client library creation - this class saves the files generated by the TemplateClientGenerator class to the disk.
TemplateClientGenerator.php - The Client Library Generator script, this class parses the API reflection xml schema and create the client library files contents.

Either create a new class and extend TemplateClientGenerator.php or directly modify TemplateClientGenerator.php code. Change the following functions to create classes and files in your programming language of choice:

writeEnum - Parses Enum (aka. types) classes.
writeObjectClass - Parses Object (aka. VO) classes.
writeService - Parses Services and actions (calls that can be performed on the objects).
writeMainClass - Create the main class of the client library, may parse Services and actions.
writeProjectFile - Create the project file (if needed).

At the end of every function un-comment the following line: $this->addFile('path to new file', 'file contents');
This call will add the new file to an internal array, this is the list of files that will be saved to the disk.

Helper functions

ClientGeneratorFromXml provides the following helper functions to ease development

setParam / getParam - An interface to add custom parameters during generation (this can be used to create configurable client libraries, e.g. the flash and flex client libraries are generated from the same generator class, by default it creates the flash library, however, when passing a parameter 'type' with value of 'flex_client' the generator will create a Flex library).
endsWith - Test if a given string ends with another string.
beginsWith - Test if a given string starts with another string.

PHP Reflection Generator

In addition to the method of using the schema XML, there is also a method of creating a Client Library Generator by extending the ClientGeneratorFromPhp class.
The ClientGeneratorFromPhp class provides a reflection mechanism that doesn't require the step of creating or downloading the schema xml.
However, this method require that the full server will be deployed and configured. This method should be treated as deprecated and be avoided.