002 API artifacts

• Status: accepted
• Deciders: partners

Context and Problem Statement

Which artifacts must be provided to data client implementors?

Decision Drivers

• extensibility: how easy is it to integrate new data clients
• upgradability: how much must be done to switch to new API versions
• usability: how easily can errors in the custom scrips and in the configuration be detected

Considered Options

• c header file(s) and shared library
• only c header file(s)

Decision Outcome

only c header file(s)

Pros and Cons of the Options

c header file(s) and shared library

Data client implementations can use c header files and also a library implementing TEK functions called from data clients.

• Good, because the execution flow is easily understandable (less usage of callback functions)
• Good, because the interface is easier to read and understand
• Bad, because it binds the data client to a specific south API binary
• Bad, because all TEK implementations are bound to a specific south API binary
• Bad, because backwards compatibility of binary and header files must be considered

only c header file(s)

Data client implementations use c header files containing among other definitions a function pointer based definition of TEK functions called from data clients. An instance of a TEK interface is then provided to a data client on start up.

i.e.:

interface tek {
    // ...
    void notify_event(data_client,...);
    void notify_condition(data_client,...);
    // ...
};

• Good, because no binary dependency for data clients
• Good, because no binary dependency for TEK implementations
• Good, because backwards compatibility only for header files must be considered
• Bad, because it may be more difficult to handle function pointers instead of direct library calls

Remarks

Wrapping managed (Java, CLR) data client implementations with native wrappers

In case an already existing basic managed data client library exists where a complete rewrite with native C code would be too much of a hassle there is the possibility/necessity of wrapping managed libraries with the proposed C south API for the transformation engine.

This may be done as separately started processes or by using the integration apis:

• JVM
• CLR