(1) A Proposal for the Java Public Middleware API Vito Baggiolini SL/CO

(2) Outline Requirements Set/Get –basic principle –Interaction diagrams –Java data types –Overloaded vs. simple methods –Exceptions MonitorOn/Off Data conversions Synchronization between threads

(3) Premisses This is a proposal –intended as a productive compromise –quite some work, but needs to be discussed This is not the BeansAPI –rather an enhanced version of Java CDEV API –BeansApi can be placed on top of this Integration with Private MoM Client API is necessary

(4) Outline Requirements Set/Get –basic principle –Interaction diagrams –Java data types –Overloaded vs. simple methods –Exceptions MonitorOn/Off Data conversions Synchronization between threads

(5) Requirements Functional Requirements –Set/get access to (virtual) devices sync and async cycle-dependent or immediate –Monitoring of device properties on-change or cycle-dependent Non-functional requirements –Simple but complete –Generic (use in different types of applications) –“True” Java –Type safe (as far as possible)

(6) “Simple” and “True Java” Object instead of Data/DataEntry (user should not have to pack and unpack structures) Use normal Java classes (not Data ) for compo- site data structures Overloaded methods where appropriate Use return to return value in get() operations Use Exceptions for error handling Use Reflection for generic stuff

(7) Design Overview One generic RemoteDevice class –one RemoteDevice object per device instance –set/get, monitorOn/Off methods –no Context! Constructor: RemoteDevice(String devClass, String devInstance); Set/Get methods: setXXX(PropName, Value, …); XXX = Int, Double, Object etc. Value = getXXX(PropName,…); Monitoring methods: MonToken = monitorOn(PropName, Listener); MonToken = monitorOn(PropName, CycleSel, Listener); monitorOff(MonToken); Almost all methods throw exceptions!

(8) Outline Requirements Set/Get –basic principle –Interaction diagrams –Java data types –Overloaded vs. simple methods –Exceptions MonitorOn/Off Data conversions Synchronization between threads

(9) Set/Get Synchronous get/set int getInt(String propName); void setInt(String propName, int value); Asynchronous get/set void getInt(String propName, ReplyListener rl); Cycle-dependent, asynchronous get/set void getInt(String propName, CycleSelector sel, ReplyListener rl); Filtered 1, cycle-dependent, asynchronous get/set void getInt(String propName, CycleSelector sel, Filter f, ReplyListener rl); 1) Filter is for server-side filtering of property data

(10) Set/Get Variants void getInt(String propName, CycleSelector sel, Filter f, ReplyListener rl); CycleSelector == null: same as cycle-independent Filter == null: no filtering ReplyListener == null: one-way (“fire&forget”)

(11) : RemoteDeviceClient : Data : OrbClient : DataEntry setInt(String, int) DeviceProxy(String) insertInt( ) add( ) set(IoPoint, Data) Synchronous set

(12) : RemoteDeviceClient : Data : OrbClient : DataEntry DeviceProxy(String) getInt(String) get(IoPoint) remove( ) extractInt( ) Synchronous get

(13) : RemoteDevice : ResultHandle getInt(String, ReplyHandler) Client do other things... : OrbClient : Data get(IoPoint) slow get action Async get handle(Data)

(14) Data Types in Java Java has the following data types: –8 primitive types (int, long, float, double, byte, boolean, char) they cannot be accessed as Object –All the rest can be treated as Object (even an Array of primitive types is an Object) –Java 1.1 defines Classes corresponding to primitive types (Integer, Long, Float, Double, Byte Boolean, Character) these can be accessed as Object! Design Issue: separate or combined methods ?

(15) Proposal: separate methods One group of methods per primitive type setInt() setLong() setFloat() setDouble() setByte() setChar() setBoolean() One group of methods for Object types setObject() can be used for anything, including Arrays and Data/DataEntry Complex data types are passed with setObject() they are extracted and packed into Data/Data- Entry using Reflection

(16) Why Methods for primitive Types? Why not use setObject() also for primitive types? Example: set/get of an int –set: setInt(value); setObject(new Integer(value)); –get: value = getInt(); value = ((Integer)getObject()).intValue();  A bit clumsy, isn’t it? Many methods are no problem! –for user: as long as they are consistent and logical (and: IDE’s represent overloaded methods as one) –for performance: methods are dispatched with hashtable

(17) Multiple Methods in JBuilder

(18) Exceptions java.rmi.RemoteException : if a problem is encountered in Middleware or in device java.lang.InvalidArgumentException : if bad information is passed to a method, (e.g. an object with bad contents to setObject)

(19) Outline Requirements & Design Principles Set/Get –basic principle –Java data types –Overloaded vs. simple methods –Exceptions –Interaction diagrams MonitorOn/Off Data conversions Synchronization between threads

(20) MonitorOn/Off Monitor a property on-change: MonToken monitorOn(String propName, monListener l); void monitorOff(MonToken mt); Monitor with CycleSelector: MonToken monitorOn(String propName, CycleSelector cs, monListener l); Monitor all properties of an Instance (required?) MonToken MonitorAll(monListener l); MonitorToken automatically unsubscribes if abandoned –Based on Java Garbage Collection ( finalize )

(21) client : MonitoringToken : SubscriptionHandle : DataListener : Mom/Orb? : RemoteDevice monitorOn(String, DataListener) monitorOn(IoPoint, Listener) MonitorOn

(22) Client : RemoteDeviceJVM : SubscriptionHandle : MonitoringToken monitorOff(MonitoringToken) getSubHandle( ) monitorOff(SubscriptionHandle) Client-initiated monitorOff finalize( ) getSubHandle( ) monitorOff(SubscriptionHandle) Automatic monitorOff Garbage Collection via Java : Mom/Orb? monitorOff(SubscriptionHandle) MonitorOff

(23) Outline Requirements & Design Principles Set/Get –basic principle –Java data types –Overloaded vs. simple methods –Exceptions –Interaction diagrams MonitorOn/Off Data conversions Synchronization between threads

(24) Conversion Data  Java types With a static DataConverter class Methods: Converter.getAsData(Object val); Converter.getAsObject(Data val); Converter.getAsData(int val); Converter.getAsInt(Data val); etc... Based on Java Reflection

(25) Outline Requirements & Design Principles Set/Get –basic principle –Java data types –Overloaded vs. simple methods –Exceptions –Interaction diagrams MonitorOn/Off Data conversions Synchronization between threads

(26) Callbacks and Synchronization Problem: primary and callback thread need to be synchronized Synchronization can be tricky!  Provide synchronization facilities in Middleware Framework Pattern “FutureReply” for Async set/get

(27) FutureReply Pattern By Greg Lavender and Doug Lea A pattern... –Based on a 1-slot buffer with locking –Enables a producer and a consumer thread to reliably exchange data items 3 Methods: –put() : for producer to put data item into buffer –get(timeout) : for consumer to wait and take data item when it’s ready (blocking) –isReady() : for consumer to check if data is there

(28) : RemoteDevice FutureReply : ResultHandle getInt(String, ReplyHandler) Client do other things... : OrbClient : Data get(IoPoint) slow get action Async get with FutureReply (1)

(29) : RemoteDevice FutureReply : ResultHandle : OrbClient : Data isReady( ) handle(Data) getInt(timeout) Check if result is avaliable Block until result is available (with timeout) Client do other things... slow get action Async get with FutureReply (2)

(30) Our FutureReply Variant Should have get methods similar to those of RemoteDevice –FutureReply’s getXxx() method matches type of retrieved value –Sync: double res = device.getDouble(propName); –Async: void getString(propName, futureReply); double res = futureReply.getDouble(); FutureReply’s getXxx() methods throw Exceptions

(31)