Best Practice Tooling

Assumptions of this guide

Imagine you have a ready-to-run ADTF Session where everything has already been setup for you by another user. It is very nice that the ADTF tools can interact with each other. You can for example launch an ADTF Session with a single click (or key) from the ADTF Configuration Editor. But keep in mind that there are multiple ways to launch an ADTF Session. This guide will give you hints on what method to use for a given use-case.

Let's say we have following user types or roles within ADTF:

  • Component Developer
  • Session Designer
  • Runtime User
  • The role of the Component Developer is clear: using the ADTF SDK to usually implement an ADTF Component (Filter, Streaming or System Service) - and hopefully some tests as well. After compiling the source code, the ADTF Plugin Description Generator will generate the plugindescription for the adtfplugin (the binary which contains the ADTF Component) to use within the ADTF Configuration Editor. This is the time to open this tool and putting this ADTF Component into an ADTF Graph, which will be used within an ADTF Session. Of course one single person can do both or all user steps, but the scope and role is definetly switching. So here we are talking about a Session Designer who has the job, to configure a launchable ADTF Session. For testing issues, this user will launch the ADTF Session to see how it works - and uses the convinience to launch it directly from ADTF Configuration Editor with the prefered launch option. After everything is fine, the ADTF Session will be stored and can be used by other users, who are interested in the runtime of the ADTF System - let's call them Runtime Users. They do not have to open the ADTF Configuration Editor again, load the ADTF Project with the required ADTF Session and launch it from there - they can launch the ADTF Session directly without any unnecessary steps or overhead.

    These roles are the basis for the following use-cases. Let's have a more detailed look:

    Create or edit ADTF Sessions before launching

    As mentioned before, some user has to design an ADTF Session to launch it later. Best way to do this is using the ADTF Configuration Editor to create an ADTF Graph, define the required dependencies within the ADTF System (which is done mostly automatically) and configure the behaviour by connecting ADTF Components regarding data and control flow, interface bindings and related property set. That's it.

    By the way... did you know since ADTF 3.6.0 you can also execute the ADTF Configuration Editor as a Runtime User, but only in Read-Only Mode to view the ADTF Sessions, ADTF Graphs and properties without edit functionality (this is still part of the Developer License). So these are the restrictions, other functions like launching tools or ADTF Sessions or navigate from Home View will work the same.

    A possible and alternate way will be the headless ADTF Config Tool. This will be recommended in scripting automatization or very small or testing setups without much overhead, as well as for CLI nerds...

    Inspect ADTF Sessions before launching

    If you only want to view how the ADTF Graph is designed, connected and configured, then simply open the ADTF Configuration Editor. And of course use the direct launch options if you want to launch the ADTF Session in addition.

    If you do not require graphical information about ADTF Graph and stuff, then you can use the ADTF Config Tool to receive the property values, ADTF Components and connections. This might be very useful also in scripting setups.

    Adapt ADTF Sessions before launching

    If you have a lot to change or do not know yet, the ADTF Configuration Editor is the best choice. But if you only want to do some basic stuff, like changing properties, connect/disconnect ADTF Components and more, the smaller ADTF Config Tool might be a good solution - especially in headless environments.

    Launch ADTF Sessions

    If you only have to process data and do not have to change, control or anything else, the easiest way is using the ADTF Launcher standalone. This does not mean that data is "only processing" - depends on your setup there might be some user interactions from UI Services defined in your ADTF System.

    Request information from running ADTF Sessions

    The main difference between ADTF Configuration Editor / ADTF Config Tool and ADTF GUI Control / ADTF Control is the first-named are related to configuration time (create, edit or view an ADTF Session / XML files on disk), the second-named are for runtime (launching, connecting or interacting with an ADTF Session / ADTF System instance).

    So to receive or watch runtime information of running ADTF instances, e.g. property values, we are talking about using ADTF Control with a powerful set of functionality, especially in scripting automatization. If you prefer some more user interactions, feel free to use ADTF GUI Control, maybe in combination with ADTF Property Editor Tool.

    Adapt ADTF Sessions after launching

    Sometimes it is necessary to make some changes or other interactions during runtime. We recommend the ADTF Control for launching or connecting (attach to an already running ADTF System). If you prefer UI, please refer to ADTF GUI Control in combination with the ADTF Property Editor Tool. But this solution might not be so powerful than the CLI way.

    Remote control several ADTF Sessions

    Maybe the ADTF GUI Control has not the whole function set than the headless ADTF Control - but when you want to control, launch or connect to more than one ADTF instance, this is a very comfortable way to do so without manual scripting steps and nice view by tabs. You can use the CLI as well, but we recommend only in scripting automatization. But all other use cases might be better using some User Interface with different tabs for better overview - extended by ADTF Log View Tool, ADTF Status Monitor or ADTF Property Editor Tool and others which cover your needs.

    Conclusion

    Here is a short summary of our recommendations:

  • We differ between configuration time (before launch) and runtime (after launch)
  • The best choice for configuration time is the ADTF Configuration Editor
  • For performing automated changes to an ADTF Session, we recommend the ADTF Config Tool
  • The best solution for runtime activities will be provided by the ADTF Control including own shell interaction mode
  • It provides also a command interface for scripting automatization
  • The ADTF GUI Control is a comfortable optional UI, especially when controling several ADTF instances at once
  • If not configured as UI Service in the ADTF System, the ADTF Log View Tool (for logging output), the ADTF Status Monitor (resource and kernel information) and the ADTF Property Editor Tool (for property access) are recommended additions for using the ADTF GUI Control
  • Launching from ADTF Configuration Editor is only necessary for development issues or after you have to view or edit ADTF Sessions before launching
  • Otherwise we recommend using the ADTF Launcher standalone or - if RPC interaction a.k.a. remote control is required - ADTF Control / ADTF GUI Control without opening the ADTF Configuration Editor before and reduce overhead
  • Also take a look at

    ... the ADTF Plugin Description Generator is a very important command line tool to generate all meta information about your adtfplugin to use within the ADTF Configuration Editor. We recommend to integrate it in your post build step by using our CMake Macro and never think about using it yourself manually, there is no need for that.

    ... the ADTF Datdump Tool does not have any connection for designing ADTF Sessions or runtime behaviour. It is just a little command line tooling if you want a quick look into an ADTFDAT recording.

    ... the Profiler GUI is a very powerful and helpful UI if you have to inspect perfomance issues within your runtime behaviour and find maybe deadlocks or long running functions. You will love it ! Look at the options and the guide how to use it (e.g. by using a Launcher with enabled profiling), but that's a parallel or post task beside the assumptions of this guide.

    ... the Licenser Tool is one of the most important tools, because you require at least a valid Runtime License. But in almost 99% of all use cases, you will use this tool only once - before all your work with ADTF is starting. Maybe you are working generic on different machines, then simply integrate the request and load or store of license by integrate it into your scripting automatization.

    ... the ADTF DAT Tool is a 3rd party delivery from ADTF File Library and a complete independent task from this behaviour: To import or export data from/to an ADTFDAT File.

    Where to go next?

    Have a look at the Best Practice Session Design to get some advices regarding the design of ADTF Session's.