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

(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



(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



(9)

Set/Get• Synchronous get/set

int getInt(String propName);

void setInt(String propName, int value);

• Asynchronous get/setvoid getInt(String propName, ReplyListener rl);

• Cycle-dependent, asynchronous get/setvoid getInt(String propName, CycleSelector sel,

ReplyListener rl);

• Filtered1, cycle-dependent, asynchronous get/setvoid getInt(String propName, CycleSelector sel,

Filter f, ReplyListener rl);

1) Filter is for server-side filtering of property data

(10)

Set/Get Variantsvoid 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)<create>

DeviceProxy(String)

insertInt( )

<create>

add( )

set(IoPoint, Data)

<error handling>

<return>

Synchronous set

(12)

: RemoteDeviceClient : Data : OrbClient : DataEntry

DeviceProxy(String)

getInt(String)get(IoPoint)

<return Data>remove( )

extractInt( )

<return result>

Synchronous get

(13)

: RemoteDevice: ResultHandle

<create>

<create>

getInt(String, ReplyHandler)

<create and pack>

Client

do other things...

: OrbClient : Data

get(IoPoint)

slow get action

Async get

handle(Data)

<unpack>

(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 typesetInt() setLong() setFloat() setDouble() setByte() setChar() setBoolean()

• One group of methods for Object typessetObject() 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


(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)

<create>

monitorOn(IoPoint, Listener)

<return SubscriptionHandle>

<create>

<create>

<return MonitoringToken>

MonitorOn

(22)

Client : RemoteDeviceJVM : SubscriptionHandle : MonitoringToken

monitorOff(MonitoringToken)

getSubHandle( )

monitorOff(SubscriptionHandle)

Client-initiated monitorOff

<abandon>

finalize( )getSubHandle( )


Automatic monitorOff

Garbage Collectionvia Java

: Mom/Orb?


MonitorOff

(23)




(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)




(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)

: RemoteDeviceFutureReply : ResultHandle

<create>

<create>

getInt(String, ReplyHandler)

<create and pack>

Client

do other things...

: OrbClient : Data

get(IoPoint)

slow get action

Async get with FutureReply (1)

(29)

: RemoteDeviceFutureReply : ResultHandle : OrbClient : Data

isReady( )

handle(Data)

getInt(timeout)

Check if result is avaliable

Block until result is available (with timeout)

Client

do other things...

<return of get()>

slow get action

<unpack>

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

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

Documents