eWON JTK

com.ewon.ewonitf
Class IOTag

java.lang.Object
  extended by com.ewon.ewonitf.IOTag

public class IOTag
extends Object

This object represents a Tag managed by a Java IO Server.
In a typical workflow, this Tag object is created when the eWON Core calls the IOServer.onGetIoInfo(java.lang.String, java.lang.String) function. This call will then be followed by a IOServer.onAdviseIo(com.ewon.ewonitf.IOTag) and the Tag will have to be managed by the IO Server until an IOServer.onUnadviseIo(com.ewon.ewonitf.IOTag) call is issued from the eWON Core.
Many IOServer's functions interract with IOTag objects, but if required you can extend your own IOTag class to hold additional data.

Since:
javaetk 1.4

Field Summary
static int QUALITY_BAD
          Used in setQuality(int) to define if the tag quality is NOT ok.
static int QUALITY_GOOD
          Used in setQuality(int) to define if the tag quality is ok.
 
Constructor Summary
IOTag(String topicName, String ioName, int defaultDataType, boolean isOutput)
          The IOTag object is used to manage one tag in the IOServer.
The user will need to instantiate this type of object in the IOServer.onGetIoInfo(java.lang.String, java.lang.String) implementation.
 
Method Summary
 void adviseTag(int postChangeId, int adviseDataType)
          Internal: This function is called automatically before the IOServer.onAdviseIo(com.ewon.ewonitf.IOTag) function is called in you IOServer.
You do not need to call this function.
 int getAdviseDataType()
           
 int getAdviseResId()
          Internal.
 void getData(IOValue ioData)
          This function must be called to change the internal IOTag value according to the value in an IOValue object which is used to exchange tag values with the eWON core.
You cannot directly pass the value to the eWON core, instead you need to use the IOValue object to do so.
 int getDefaultDataType()
           
 IOValue getIoData()
           
 String getIoName()
           
 int getPostChangeId()
          Required to call IOServer.postIoChange(com.ewon.ewonitf.IOTag).
 int getQuality()
           
 String getTopicName()
           
 boolean getValueBoolean()
          This function is used to retreive the current tag's value if defaultDataType is IOValue.DATATYPE_BOOLEAN.
 float getValueFloat32()
          This function is used to retreive the current tag's value if defaultDataType is IOValue.DATATYPE_FLOAT32.
 int getValueInt32()
          This function is used to retreive the current tag's value if defaultDataType is IOValue.DATATYPE_INT32.
 long getValueUInt32()
          This function is used to retreive the current tag's value if defaultDataType is IOValue.DATATYPE_UINT32.
 boolean isAdvised()
          Indicates if the tag adviseTag(int, int) function was already called or not.
 boolean isOutput()
           
 void setQuality(int q)
          Assign the current tag quality value.
To propagate the quality change to the eWON Core, you also need to call the IOServer.postQuality(com.ewon.ewonitf.IOTag) after the tag's quality has been set by this function.
 void setValueBoolean(boolean value)
          This function must be called to update the internal IOTag value of the tag if defaultDataType is IOValue.DATATYPE_BOOLEAN.
 void setValueFloat32(float value)
          This function must be called to update the internal IOTag value of the tag if defaultDataType is IOValue.DATATYPE_FLOAT32.
 void setValueInt32(int value)
          This function must be called to update the internal IOTag value of the tag if defaultDataType is IOValue.DATATYPE_INT32.
 void setValueUInt32(long value)
          This function must be called to update the internal IOTag value of the tag if defaultDataType is IOValue.DATATYPE_UINT32.
 void unAdviseTag()
          Internal: This function is called automatically after the IOServer.onUnadviseIo(com.ewon.ewonitf.IOTag) function is called in you IOServer.
You do not need to call this function.
 void updateTag(IOValue ioData)
          This function must be called to write the internal IOTag value in an IOValue object which is used to exchange tag values with the eWON core.
You cannot directly pass the value to the eWON core, instead you need to use the IOValue object to do so.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

QUALITY_GOOD

public static final int QUALITY_GOOD
Used in setQuality(int) to define if the tag quality is ok.

See Also:
Constant Field Values

QUALITY_BAD

public static final int QUALITY_BAD
Used in setQuality(int) to define if the tag quality is NOT ok.

See Also:
Constant Field Values
Constructor Detail

IOTag

public IOTag(String topicName,
             String ioName,
             int defaultDataType,
             boolean isOutput)
The IOTag object is used to manage one tag in the IOServer.
The user will need to instantiate this type of object in the IOServer.onGetIoInfo(java.lang.String, java.lang.String) implementation. When onGetIoInfo is called, the topicName and IOName are provided, the user must determine the default datatype for the tag and if the tag is writable (isOutput). We only care about the tags which are "advised", this means that they have been registered by the eWON and the eWON needs to be alerted about any change on the tag.

Parameters:
topicName -
ioName -
defaultDataType - This is type which is closer to the actual value stored in the tag.
For example, if you have a 16Bit signed register in a modbus driver, an INT32 is appropriate.
If you store integer values in floats, you will increase the CPU required to manage the value and you may lose precision when converting integer to float and back.
isOutput - Indicates if this tag can be written by the eWON application. False if the tag is read-only. For example if the tag is connected to a digital input, it will be isOutput == false.
Method Detail

isAdvised

public boolean isAdvised()
Indicates if the tag adviseTag(int, int) function was already called or not.

Returns:

getTopicName

public String getTopicName()
Returns:
Topic Name passed during object creation (see IOTag()).

getIoName

public String getIoName()
Returns:
IO Name passed during object creation (see IOTag()).

isOutput

public boolean isOutput()
Returns:
The value passed to isOutput during object creation (see IOTag()).

getDefaultDataType

public int getDefaultDataType()
Returns:
The value passed to DefaultDataType during object creation (see IOTag()).

adviseTag

public void adviseTag(int postChangeId,
                      int adviseDataType)
Internal: This function is called automatically before the IOServer.onAdviseIo(com.ewon.ewonitf.IOTag) function is called in you IOServer.
You do not need to call this function.

Parameters:
postChangeId - Passed during onAdviseIo
adviseDataType - Passed during onAdviseIo

unAdviseTag

public void unAdviseTag()
Internal: This function is called automatically after the IOServer.onUnadviseIo(com.ewon.ewonitf.IOTag) function is called in you IOServer.
You do not need to call this function. This will release some resources allocated during advise and will mark the tag as not advise when calling isAdvised().


getIoData

public IOValue getIoData()
                  throws Exception
Returns:
The internal IOValue object representing the current IOTag value.
Throws:
Exception - in case the internal representation cannot be converted to the internal IOValue.

getAdviseDataType

public int getAdviseDataType()
Returns:
Type used to advise the tag in the eWON (may be different from the default type).

getAdviseResId

public int getAdviseResId()
Internal.

Returns:
An information required when advising the tag.

getQuality

public int getQuality()
Returns:
Current tag quality as set by setQuality(int), defaults to QUALITY_GOOD after creation.

setQuality

public void setQuality(int q)
                throws Exception
Assign the current tag quality value.
To propagate the quality change to the eWON Core, you also need to call the IOServer.postQuality(com.ewon.ewonitf.IOTag) after the tag's quality has been set by this function.

Parameters:
q - on of QUALITY_GOOD or QUALITY_BAD
Throws:
Exception - if quality passed is invalid.

getPostChangeId

public int getPostChangeId()
Required to call IOServer.postIoChange(com.ewon.ewonitf.IOTag). The postChangeId is passed during tag Advise and saved with #setAdviseInfo. The value can then be retreived with this function.

Returns:
postChangeId passed by #setAdviseInfo.

setValueUInt32

public void setValueUInt32(long value)
                    throws Exception
This function must be called to update the internal IOTag value of the tag if defaultDataType is IOValue.DATATYPE_UINT32. IOTag requires to maintains internally the tag value. Thus, you need to call one of the setValueXXX and getValueXX to read and write the tag value.
You need to use the setValueXXX according to the defaultDataType passed during IOTag creation, if you fail to call the right setValueXXX an exception will be thrown.

Parameters:
value - The new tag's value.
Throws:
Exception - In case the defaultDataType passed to IOTag#IOTag(int, boolean) is not IOValue.DATATYPE_UINT32.

setValueInt32

public void setValueInt32(int value)
                   throws Exception
This function must be called to update the internal IOTag value of the tag if defaultDataType is IOValue.DATATYPE_INT32. IOTag requires to maintains internally the tag value. Thus, you need to call one of the setValueXXX and getValueXX to read and write the tag value.
You need to use the setValueXXX according to the defaultDataType passed during IOTag creation, if you fail to call the right setValueXXX an exception will be thrown.

Parameters:
value - The new tag's value.
Throws:
Exception - In case the defaultDataType passed to IOTag#IOTag(int, boolean) is not IOValue.DATATYPE_INT32.

setValueFloat32

public void setValueFloat32(float value)
                     throws Exception
This function must be called to update the internal IOTag value of the tag if defaultDataType is IOValue.DATATYPE_FLOAT32. IOTag requires to maintains internally the tag value. Thus, you need to call one of the setValueXXX and getValueXX to read and write the tag value.
You need to use the setValueXXX according to the defaultDataType passed during IOTag creation, if you fail to call the right setValueXXX an exception will be thrown.

Parameters:
value - The new tag's value.
Throws:
Exception - In case the defaultDataType passed to IOTag#IOTag(int, boolean) is not IOValue.DATATYPE_FLOAT32.

setValueBoolean

public void setValueBoolean(boolean value)
                     throws Exception
This function must be called to update the internal IOTag value of the tag if defaultDataType is IOValue.DATATYPE_BOOLEAN. IOTag requires to maintains internally the tag value. Thus, you need to call one of the setValueXXX and getValueXX to read and write the tag value.
You need to use the setValueXXX according to the defaultDataType passed during IOTag creation, if you fail to call the right setValueXXX an exception will be thrown.

Parameters:
value - The new tag's value.
Throws:
Exception - In case the defaultDataType passed to IOTag#IOTag(int, boolean) is not IOValue.DATATYPE_BOOLEAN.

getValueUInt32

public long getValueUInt32()
                    throws Exception
This function is used to retreive the current tag's value if defaultDataType is IOValue.DATATYPE_UINT32. You need to use the setValueXXX according to the defaultDataType passed during IOTag creation, if you fail to call the right setValueXXX an exception will be thrown.

Returns:
The tag's value.
Throws:
Exception - In case the defaultDataType passed to IOTag#IOTag(int, boolean) is not IOValue.DATATYPE_UINT32.

getValueInt32

public int getValueInt32()
                  throws Exception
This function is used to retreive the current tag's value if defaultDataType is IOValue.DATATYPE_INT32. You need to use the setValueXXX according to the defaultDataType passed during IOTag creation, if you fail to call the right setValueXXX an exception will be thrown.

Returns:
The tag's value.
Throws:
Exception - In case the defaultDataType passed to IOTag#IOTag(int, boolean) is not IOValue.DATATYPE_INT32.

getValueFloat32

public float getValueFloat32()
                      throws Exception
This function is used to retreive the current tag's value if defaultDataType is IOValue.DATATYPE_FLOAT32. You need to use the setValueXXX according to the defaultDataType passed during IOTag creation, if you fail to call the right setValueXXX an exception will be thrown.

Returns:
The tag's value.
Throws:
Exception - In case the defaultDataType passed to IOTag#IOTag(int, boolean) is not IOValue.DATATYPE_FLOAT32.

getValueBoolean

public boolean getValueBoolean()
                        throws Exception
This function is used to retreive the current tag's value if defaultDataType is IOValue.DATATYPE_BOOLEAN. You need to use the setValueXXX according to the defaultDataType passed during IOTag creation, if you fail to call the right setValueXXX an exception will be thrown.

Returns:
The tag's value.
Throws:
Exception - In case the defaultDataType passed to IOTag#IOTag(int, boolean) is not IOValue.DATATYPE_BOOLEAN.

updateTag

public void updateTag(IOValue ioData)
               throws Exception
This function must be called to write the internal IOTag value in an IOValue object which is used to exchange tag values with the eWON core.
You cannot directly pass the value to the eWON core, instead you need to use the IOValue object to do so.

Parameters:
ioData - Opaque object used to exchange tag values with the eWON core. The IOTag's value will be written in this ioData.
Throws:
Exception - In case the defaultDataType is not set or the adviseDataType is not set.

getData

public void getData(IOValue ioData)
             throws Exception
This function must be called to change the internal IOTag value according to the value in an IOValue object which is used to exchange tag values with the eWON core.
You cannot directly pass the value to the eWON core, instead you need to use the IOValue object to do so.

Parameters:
ioData - Opaque object used to exchange tag values with the eWON core. The IOTag's value will be changed according to this ioData.
Throws:
Exception - In case the defaultDataType is not set or the adviseDataType is not set.

eWON JTK

www.eWON.biz: Your Eyes Watching Over Net