eWON JTK

com.ewon.ewonitf
Class IOServer

java.lang.Object
  extended by com.ewon.ewonitf.IOServer
All Implemented Interfaces:
EvtListener

public abstract class IOServer
extends Object
implements EvtListener

This is an abstract class from which an IO Server class can be created.
Please read the "eWON Java interface user guide" for more information.

Since:
javaetk 1.4

Field Summary
static int STATUS_DEAD
          use with setGetServerStatus(int, int) to set the server status to DEAD (if Java code is not able to handle IOServer operations)
static int STATUS_INIT
          use with setGetServerStatus(int, int) to set the server status to INIT (not used normaly)
static int STATUS_READY
          use with setGetServerStatus(int, int) to set the server status to READY (after listener was added)
 
Constructor Summary
IOServer()
          Create an instance of the IO Server.
 
Method Summary
 void call(int eventHandler, String nullStr, int iHandle)
          Internal use only, this will trigger execution of the requested IO Server function
 String getConfigParam(String paramName, String defaultValue)
          Read one parameter for the user defined configuration.
 int getInstanceHandle()
          Internal function
 IOTag getIOTag(String topicName, String ioName)
          This function will find a tag in a topic.
abstract  void onAdviseIo(IOTag ioTag)
          Called when a new tag is advised.
 IOValue onGetIo(IOTag ioTag)
          This is the function called when the eWON needs to read the tag value.
abstract  IOTag onGetIoInfo(String topicName, String ioName)
          This is the first function called when trying to access a new IOName.
abstract  void onPassConfig(boolean applyConfig, boolean checkConfig)
          Called by the eWON when the IO Server configuration is updated, or tho check if the proposed configuration is valid.
The configuration is encoded as a serie of string parameters with the format ParamName:ParamValue, when this onPassConfig handler is called, the program should read the parameters one by one using getConfigParam(java.lang.String, java.lang.String).
 void onPutIo(IOTag ioTag, IOValue ioValue)
          This is the function called when the eWON wants to update the tag.
 void onRegister()
          This callback is called during registration just before the IOServer is marked as ready.
abstract  void onUnadviseIo(IOTag ioTag)
           
 void postIoChange(IOTag ioTag)
           
 void postQuality(IOTag ioTag)
           
 void registerServer()
          Call this function to register the IO server.
The registration is a 2 steps process, first this function must be called, it will instantiate the IOServer in the native eWON Core.
static int setGetServerStatus(int iHandle, int status)
          Adjust the server status.
protected  void setJavaReplyTimeout(int timeout)
          Adjust reply timeout to events posted to Java.
protected  void setServerName(String name)
          Define the IO Server name.
protected  void setTagHelper(String tagHelper)
          Define the IOServer tag helper string.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

STATUS_INIT

public static final int STATUS_INIT
use with setGetServerStatus(int, int) to set the server status to INIT (not used normaly)

See Also:
Constant Field Values

STATUS_READY

public static final int STATUS_READY
use with setGetServerStatus(int, int) to set the server status to READY (after listener was added)

See Also:
Constant Field Values

STATUS_DEAD

public static final int STATUS_DEAD
use with setGetServerStatus(int, int) to set the server status to DEAD (if Java code is not able to handle IOServer operations)

See Also:
Constant Field Values
Constructor Detail

IOServer

public IOServer()
Create an instance of the IO Server.

Method Detail

setServerName

protected void setServerName(String name)
Define the IO Server name. Typically used during child object construction, and always before registration.

Parameters:
name - The string passed here will be used in uppercase during registration.

setTagHelper

protected void setTagHelper(String tagHelper)
Define the IOServer tag helper string. Typically used during child object construction, and always before registration. Please refer to the tag helper syntax use this function.
Example: (will define a minimal tag helper with only 2 topics A and B defined)
setTagHelper("{\"topic\":{ \"A\":{},\"B\":{}}}");

Parameters:
tagHelper - the string used for tag help definition (JSON syntax)

getInstanceHandle

public int getInstanceHandle()
Internal function

Returns:
Return the instance handle passed during registration. This handle is used to map events received by the listener for this IOServer.

setJavaReplyTimeout

protected void setJavaReplyTimeout(int timeout)
                            throws Exception
Adjust reply timeout to events posted to Java. When an IOServer command is posted from the eWON to the Java, the eWON expects a reply within a specific amount of time defined by this timeout. The default timeout is 2000msec which should not be increased for normal operations in order to let the firmware work normally. During developpment of the IOServer, you may want to increate the timeout to debug with step by step, but be aware that other IO servers will be frozen while the Java IO Server is blocked.
If the Java does not reply within the delay, the IO Server is considered "dead".

Parameters:
timeout - (in MSec).
Throws:
Exception - if value is invalid (minimum 100 MSec)

registerServer

public void registerServer()
                    throws Exception
Call this function to register the IO server.
The registration is a 2 steps process, first this function must be called, it will instantiate the IOServer in the native eWON Core. An instanceHandle is returned. Then the IOServer listener is added to the DefaultEventHandler (i.e.: DefaultEventHandler.addIOServerListener).
From the IOServer developer point of view this mechanism is hidden.
The onRegister() function is called just before the IOServer state is passed to STATUS_READY. A default onRegister exists and does nothing.
If you need to perform some initialisation, it is a good time to do it.
For debugging purpose, it may be necessary to register the IOServer multiple times without rebooting the eWON. This is allowed and will result in the IO Server being stopped, all tags will be disabled (unadvised) - including the tags from other IO Servers, then the configuration (config.txt) will be cleared and reloaded. All these operation will tag place during the "register" call. It is not recommended (at all), to re-register in a production environment.

Throws:
Exception - in case of error during registration.

onPassConfig

public abstract void onPassConfig(boolean applyConfig,
                                  boolean checkConfig)
                           throws Exception
Called by the eWON when the IO Server configuration is updated, or tho check if the proposed configuration is valid.
The configuration is encoded as a serie of string parameters with the format ParamName:ParamValue, when this onPassConfig handler is called, the program should read the parameters one by one using getConfigParam(java.lang.String, java.lang.String).

Parameters:
applyConfig - True if this configuration must be used.
checkConfig - True if this configuration must be checked.
Throws:
Exception - If for example the parameters passed are invalid.

onGetIoInfo

public abstract IOTag onGetIoInfo(String topicName,
                                  String ioName)
                           throws Exception
This is the first function called when trying to access a new IOName. Its main purpose is to instantiate the new tag, which will provide the default datatype and isOutput information.

Parameters:
topicName -
ioName -
Returns:
and IOTag (or descendant). Never return null, throw an exception instead.
Throws:
Exception

onRegister

public void onRegister()
                throws Exception
This callback is called during registration just before the IOServer is marked as ready. The default function defined for this event does nothing, you should redefine it if required (for example to update the reply timeout with setJavaReplyTimeout(int)).

Throws:
Exception - If an exception is thrown, the server will not become ready and not tag will be able to register.

onPutIo

public void onPutIo(IOTag ioTag,
                    IOValue ioValue)
             throws Exception
This is the function called when the eWON wants to update the tag. By default this function will simply update the tag value and post the new value. public void onPutIo(IOTag ioTag, IOValue ioValue) throws Exception { ioTag.updateTag(ioValue); postIoChange(ioTag); } REM: as you can see the ioTag value is updated with the received new value, but you also need to post this value to the eWON otherwise the eWON tag will not reflect the internal value of the tag in the IOServer. In a real IOServer the new value may need to be written to a field bus, then read back and only at that time the actual would be posted to the eWON using postIoChange(com.ewon.ewonitf.IOTag)

Parameters:
ioTag - The tag for which the new value was written.
ioValue - The new value (with Advise DataType)
Throws:
Exception

onGetIo

public IOValue onGetIo(IOTag ioTag)
                throws Exception
This is the function called when the eWON needs to read the tag value. This function will return the current tag value. If you want to intercept the call to update the internal value you can override this method.
The default implementation is:
public IOValue onGetIo(IOTag ioTag) throws Exception { return ioTag.getIoData(); }

Parameters:
ioTag -
Returns:
Throws:
Exception

onAdviseIo

public abstract void onAdviseIo(IOTag ioTag)
                         throws Exception
Called when a new tag is advised. This function must be defined so that the IO Server can monitor and handle a new tag. The ioTag passed has already the correct name (IOTag.getIoName()) and the correct internal data type (IOTag.getDefaultDataType()).

Parameters:
ioTag - The IOTag object created by the IOServer object, you should keep a reference to this IOTag in your code to update its value when required and post the new value to the eWON.
Throws:
Exception

onUnadviseIo

public abstract void onUnadviseIo(IOTag ioTag)
                           throws Exception
Parameters:
ioTag -
Throws:
Exception

postIoChange

public void postIoChange(IOTag ioTag)
                  throws Exception
Parameters:
ioTag -
Throws:
Exception

postQuality

public void postQuality(IOTag ioTag)
                 throws Exception
Parameters:
ioTag -
Throws:
Exception

call

public void call(int eventHandler,
                 String nullStr,
                 int iHandle)
Internal use only, this will trigger execution of the requested IO Server function

Specified by:
call in interface EvtListener
Parameters:
eventHandler -
nullStr -
iHandle -

getConfigParam

public String getConfigParam(String paramName,
                             String defaultValue)
Read one parameter for the user defined configuration. This function will be called during {@link #onPassConfig(boolean, boolean) function execution to read the configuration's paramters one by one.

Parameters:
paramName - parameter's name.
defaultValue - value to use in case the user did not define the parameter.
Returns:

getIOTag

public IOTag getIOTag(String topicName,
                      String ioName)
This function will find a tag in a topic. If the topic does not exists, it will be created. If the ioName does not exists the function will return null

Parameters:
topicName -
ioName -
Returns:
The IOTag searched or null if IOTag does not exists.

setGetServerStatus

public static int setGetServerStatus(int iHandle,
                                     int status)
Adjust the server status. This function is normally used internally and should not be required by user's implementation.

Parameters:
iHandle - The instance handle received during the registration.
status - A value among STATUS_INIT,STATUS_DEAD or STATUS_READY.
if set to -1 the current status is not modified, but previous value is returned.
Returns:
Previous value of the status.

eWON JTK

www.eWON.biz: Your Eyes Watching Over Net