JAPC – the Java API for Parameter Control (Designing for Smooth Evolution)

1. JAPC – the Java API for Parameter Control(Designing for Smooth Evolution) Vito Baggiolini L. Mestre, E. Roux, G. Kruk, R. Gorbonosov (CERN - AB/CO)

2. Outline • Challenge three years ago • Java API for Parameter Controls • Three Scenarios of Evolution • Conclusions

3. General Purpose Services Specific applications GUI components Diagnostic Tools JAPC Interface JAPC core japc-cmw japc-old-mw japc-xyz ctrls middleware old “middleware” middleware xyz New Devices Old Devices Challenge Three Years Ago YXZ Devices

4. The JAPC Layer • JAPC: “Java API for Parameter Control” • Parameter a value you need to supervise and/or control (aka control value, I/O point, I/O channel, signal, device property) • Functionality provided by JAPC: • set/get and subscribe • Obtain meta-information about the parameter • JAPC = Core package + Extensions • Some numbers • JAPC core: 350 Classes, 60’000 Lines of Code; • 12 extensions: each 10-20 Classes, 1’000-3’000 Lines of Code • 3 main developer, 5 contributors; ~ 3 man years

5. JAPC Interface: Basic Abstractions • Parameter = the “handle” • provides set/get and subscribe functionality • ParameterValue = Data container • Transports all data types supported by our front-ends • Simple types (byte, int, double, String, etc) and arrays • Composite types (contain several simple types) • CycleSelector specifies when data shall be accessed • Cycle-Event: timing system event at which the data shall be acquired • Descriptor provides meta information on the parameter • for self-configuring GUI components • getDescription() • isWritable(), isReadable(), isSubscribable() • Information retrieved from CERN directory service [ MO P.M.] • ParameterFactory • a class that knows how to create parameters

6. JAPC Code example • Counter device with one parameter: • Measurement (Read-Only) Parameter p = Factory.createParameter(“Counter11”, “Measurement”); CycleSelector sel = Factory.createCycleSelector(END_OF_CYCLE); ParameterValue value = par.get(sel); int counts = value.getInt(); • Characteristics of JAPC API • Narrow API (few classes and methods) • Use of lots of strings

7. Evolution Scenario 1:old parameter types go,new parameter types come

8. General Purpose Services Specific applications GUI components Diagnostic Tools Evolution: old Stuff Disappeared JAPC Interface JAPC core japc-cmw japc-old-mw japc-xyz ctrls middleware old “middleware” middleware xyz New Devices Old Devices YXZ Devices

9. General Purpose Services Specific applications GUI components Diagnostic Tools japc-sim japc-j2ee japc-db japc-tim Simulatedparameters Virtual Devices (J2EE Server) Database or Files Timing System Evolution: New Kinds of Parameters JAPC Interface JAPC core japc-cmw controls middleware New Devices Old Devices

10. Evolution Scenario 2:accommodating new,unforeseen requirements

11. Evolution: New Requirements • New requirement: filter data coming from devices • Some instruments have acquisition parameters with very large amounts of data • E.g. images, or values(t) with high time resolution • Only a part of the data shall be sent over the network • Careful extension needed of the JAPC interface • Very reluctant to add new methods or extend signatures • “I don’t want to pollute the API” • “Old”: CycleSelector • Selects data in the time domain • Cycle-Event: timing event at which the data shall be acquired • “New”: CycleSelector became Selector • Selectsdata also in the value domain • [new] Filterfor the data (e.g. take first 100 values of an array) • Evolution by generalizing a design abstraction

12. Evolution Scenario 3:coping with changes in device design

13. Counter • Measurement • Acquisition Evolution: Modification in Device • Device developer changes “Measurement”  “Acquisition” • GUI developer adapts his code (but forgets some changes) • What happens? Counter GUI JAPC Interface JAPC core japc-cmw controls middleware • Counter • Measurement

14. What happens? • Nothing happens until the code is executed! Parameter par = F.createParameter(“Counter11”, “Measurement”); Selector sel = F.createSelector(END_OF_CYCLE); ParameterValue value = par.get(sel); *** Runtime Exception: unknown parameter “Counter11/Measurement” • Detecting an error at run time is too late! • The earlier and easier you detect an error, the better. • If possible, errors should be detected at compile time

15. Solution: JAPC Code Generation • Generate Java code based on device description (XML) • Uses XML descriptions of new FESA Devices[Fri, 9h00] • Generated everytime the product is re-built • Purpose: facilitate application programming • Less code to write manually • Safer code (strongly typed interface, compile-time checks, fewer strings) • Idea: generate a wide API to get compile time errors Specific application japc-codegen JAPC

16. <JAPC> Parameter Counter int getMeasurement() Config getConfig() setConfig(Config) Config getCalibFactor() setCalibFactor() <JAPC> Parameter Generated Classes • Counter device with two properties: • Measurement (simple, read-only) • Config (composite, read-write) • Counter c = new Counter(“Counter11”); • int counts = scint.getMeasurement(); • double factor = scint.getConfig().getCalibFactor();

17. Counter int getAcquisition() … • GUI developer regenerates codeusing japc-codegen • Counter • Measurement • Acquisition Modification in Device vs Code Generation Counter GUI • Device developer renames “Measurement”  “Acquisition” japc-codegen JAPC Interface JAPC core • He doesn’t even bother touching his GUI code • What happens? japc-cmw controls middleware • Counter • Measurement

18. Counter int getAcquisition() … • Counter • Measurement • Acquisition What happens with Code Generation? • GUI code using normal JAPC *** Runtime Exception: unknown parameter “Counter11/Measurement” • GUI code using code generation: Counter cnt = new Counter(“Counter11”); int counts = cnt.getMeasurement().getCount(); *** Compiler error: unknown method: getMeasurement()  Support for evolution: error detection at compile time

19. Conclusions • In this presentation, we’ve seen three types of evolution • Evolution form old to new technology • Evolution to support new functionality (filtering) • Evolution in hardware devices (renamed property) • JAPC managed to cope with all three of them • Designing for evolution is one of the big Software Engineering challenges • It requires talent, experience, but most of all time… • But not getting the design right requires even more time!