Package com.beanit.iec61850bean

Class ClientAssociation

java.lang.Object

com.beanit.iec61850bean.ClientAssociation

public final class ClientAssociation
extends java.lang.Object

Represents an association/connection to an IEC 61850 MMS server. An instance of ClientAssociation is obtained using ClientSap. An association object can be used to execute the IEC 61850 ACSI services. Note that not all ACSI services have a corresponding function in this API. For example all GetDirectory and GetDefinition services are covered by retrieveModel(). The control services can be executed by using getDataValues and setDataValues on the control objects in the data model.

Method Summary

Modifier and Type	Method	Description
void	cancelUrcbReservation(Urcb urcb)
void	close()	Will close the connection simply by closing the TCP socket.
void	createDataSet(DataSet dataSet)	The client should create the data set first and add it to either the non-persistent list or to the model.
void	deleteDataSet(DataSet dataSet)
void	deleteFile(java.lang.String filename)	Delete a file from the server
void	disableReporting(Rcb rcb)
void	disconnect()	Will send a disconnect request first and then close the TCP socket.
void	enableReporting(Rcb rcb)
void	getAllDataValues()	Will update all data inside the model except for control variables (those that have FC=CO).
java.util.List<ServiceError>	getDataSetValues(DataSet dataSet)	The implementation of the GetDataSetValues ACSI service.
void	getDataValues(FcModelNode modelNode)	The implementation of the GetDataValues ACSI service.
void	getFile(java.lang.String filename, GetFileListener listener)	Read a file from the server
java.util.List<FileInformation>	getFileDirectory(java.lang.String directoryName)	Read the file directory of the server
void	getRcbValues(Rcb rcb)
int	getResponseTimeout()	Gets the response timeout.
boolean	isOpen()
void	operate(FcModelNode controlDataObject)	Executes the Operate ACSI Service on the given controllable Data Object (DO).
void	reserveBrcb(Brcb brcb, short resvTime)
void	reserveUrcb(Urcb urcb)
ServerModel	retrieveModel()	Triggers all GetDirectory and GetDefinition ACSI services needed to get the complete server model.
boolean	select(FcModelNode controlDataObject)	Performs the Select ACSI Service of the control model on the given controllable Data Object (DO).
java.util.List<ServiceError>	setDataSetValues(DataSet dataSet)
void	setDataValues(FcModelNode modelNode)	The implementation of the SetDataValues ACSI service.
java.util.List<ServiceError>	setRcbValues(Rcb rcb, boolean setRptId, boolean setDatSet, boolean setOptFlds, boolean setBufTm, boolean setTrgOps, boolean setIntgPd, boolean setPurgeBuf, boolean setEntryId)	Sets the selected values of the given report control block.
void	setResponseTimeout(int timeout)	Sets the response timeout.
void	setServerModel(ServerModel model)	Set the server model instead of retrieving it from the server device.
void	startGi(Rcb rcb)
void	updateDataSets()	This function will get the definition of all persistent DataSets from the server and update the DataSets in the ServerModel that was returned by retrieveModel or set using setServerModel.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getResponseTimeout

public int getResponseTimeout()

Gets the response timeout. The response timeout is used whenever a request is sent to the server. The client will wait for this amount of time for the server's response before throwing a ServiceError.TIMEOUT. Responses received after the timeout will be automatically discarded.

Returns:

the response timeout in milliseconds.

setResponseTimeout

public void setResponseTimeout(int timeout)

Sets the response timeout. The response timeout is used whenever a request is sent to the server. The client will wait for this amount of time for the server's response before throwing a ServiceError.TIMEOUT. Responses received after the timeout will be automatically discarded.

Parameters:

timeout - the response timeout in milliseconds.

setServerModel

public void setServerModel(ServerModel model)

Set the server model instead of retrieving it from the server device.

Parameters:

model - the server model

retrieveModel

public ServerModel retrieveModel()
                          throws ServiceError,
                                 java.io.IOException

Triggers all GetDirectory and GetDefinition ACSI services needed to get the complete server model. Because in MMS SubDataObjects cannot be distinguished from Constructed Data Attributes they will always be represented as Constructed Data Attributes in the returned model.

Returns:

the ServerModel that is the root node of the complete server model.

Throws:

ServiceError - if a ServiceError occurs while calling any of the ASCI services.

java.io.IOException - if a fatal association error occurs. The association object will be closed and can no longer be used after this exception is thrown.

getDataValues

public void getDataValues(FcModelNode modelNode)
                   throws ServiceError,
                          java.io.IOException

The implementation of the GetDataValues ACSI service. Will send an MMS read request for the given model node. After a successful return, the Basic Data Attributes of the passed model node will contain the values read. If one of the Basic Data Attributes cannot be read then none of the values will be read and a ServiceError will be thrown.

Parameters:

modelNode - the functionally constrained model node that is to be read.

Throws:

ServiceError - if a ServiceError is returned by the server.

java.io.IOException - if a fatal association error occurs. The association object will be closed and can no longer be used after this exception is thrown.

getFileDirectory

public java.util.List<FileInformation> getFileDirectory(java.lang.String directoryName)
                                                 throws ServiceError,
                                                        java.io.IOException

Read the file directory of the server

Parameters:

directoryName - name of a directory or empty string for the root directory

Returns:

the list of available

Throws:

ServiceError - if a ServiceError is returned by the server or parsing of response failed.

java.io.IOException - if a fatal association error occurs. The association object will be closed and can no longer be used after this exception is thrown.

deleteFile

public void deleteFile(java.lang.String filename)
                throws ServiceError,
                       java.io.IOException

Delete a file from the server

Parameters:

filename - name of the file to delete

Throws:

ServiceError - if a ServiceError is returned by the server

java.io.IOException - if a fatal association error occurs. The association object will be closed and can no longer be used after this exception is thrown.

getFile

public void getFile(java.lang.String filename,
                    GetFileListener listener)
             throws ServiceError,
                    java.io.IOException

Read a file from the server

Parameters:

filename - name of the file to delete

listener - callback handler to receive fall data

Throws:

ServiceError - if a ServiceError is returned by the server

java.io.IOException - if a fatal association error occurs. The association object will be closed and can no longer be used after this exception is thrown.

getAllDataValues

public void getAllDataValues()
                      throws ServiceError,
                             java.io.IOException

Will update all data inside the model except for control variables (those that have FC=CO). Control variables are not meant to be read. Update is done by calling getDataValues on the FCDOs below the Logical Nodes.

Throws:

ServiceError - if a ServiceError is returned by the server.

java.io.IOException - if a fatal association error occurs. The association object will be closed and can no longer be used after this exception is thrown.

setDataValues

public void setDataValues(FcModelNode modelNode)
                   throws ServiceError,
                          java.io.IOException

The implementation of the SetDataValues ACSI service. Will send an MMS write request with the values of all Basic Data Attributes of the given model node. Will simply return if all values have been successfully written. If one of the Basic Data Attributes could not be written then a ServiceError will be thrown. In this case it is not possible to find out which of several Basic Data Attributes could not be written.

Parameters:

modelNode - the functionally constrained model node that is to be written.

Throws:

ServiceError - if a ServiceError is returned by the server.

java.io.IOException - if a fatal association error occurs. The association object will be closed and can no longer be used after this exception is thrown.

updateDataSets

public void updateDataSets()
                    throws ServiceError,
                           java.io.IOException

This function will get the definition of all persistent DataSets from the server and update the DataSets in the ServerModel that was returned by retrieveModel or set using setServerModel. It will delete DataSets that have been deleted since the last update and add any new DataSets

Throws:

ServiceError - if a ServiceError is returned by the server.

java.io.IOException - if a fatal association error occurs. The association object will be closed and can no longer be used after this exception is thrown.

createDataSet

public void createDataSet(DataSet dataSet)
                   throws ServiceError,
                          java.io.IOException

The client should create the data set first and add it to either the non-persistent list or to the model. Then it should call this method for creation on the server side

Parameters:

dataSet - the data set to be created on the server side

Throws:

ServiceError - if a ServiceError is returned by the server.

java.io.IOException - if a fatal IO error occurs. The association object will be closed and can no longer be used after this exception is thrown.

deleteDataSet

public void deleteDataSet(DataSet dataSet)
                   throws ServiceError,
                          java.io.IOException

Throws:

ServiceError

java.io.IOException

getDataSetValues

public java.util.List<ServiceError> getDataSetValues(DataSet dataSet)
                                              throws java.io.IOException

The implementation of the GetDataSetValues ACSI service. After a successful return, the Basic Data Attributes of the data set members will contain the values read. If one of the data set members could not be read, this will be indicated in the returned list. The returned list will have the same size as the member list of the data set. For each member it will contain null if reading was successful and a ServiceError if reading of this member failed.

Parameters:

dataSet - the DataSet that is to be read.

Returns:

a list indicating ServiceErrors that may have occurred.

Throws:

java.io.IOException - if a fatal IO error occurs. The association object will be closed and can no longer be used after this exception is thrown.

setDataSetValues

public java.util.List<ServiceError> setDataSetValues(DataSet dataSet)
                                              throws ServiceError,
                                                     java.io.IOException

Throws:

ServiceError

java.io.IOException

getRcbValues

public void getRcbValues(Rcb rcb)
                  throws ServiceError,
                         java.io.IOException

Throws:

ServiceError

java.io.IOException

reserveUrcb

public void reserveUrcb(Urcb urcb)
                 throws ServiceError,
                        java.io.IOException

Throws:

ServiceError

java.io.IOException

reserveBrcb

public void reserveBrcb(Brcb brcb,
                        short resvTime)
                 throws ServiceError,
                        java.io.IOException

Throws:

ServiceError

java.io.IOException

cancelUrcbReservation

public void cancelUrcbReservation(Urcb urcb)
                           throws ServiceError,
                                  java.io.IOException

Throws:

ServiceError

java.io.IOException

enableReporting

public void enableReporting(Rcb rcb)
                     throws ServiceError,
                            java.io.IOException

Throws:

ServiceError

java.io.IOException

disableReporting

public void disableReporting(Rcb rcb)
                      throws ServiceError,
                             java.io.IOException

Throws:

ServiceError

java.io.IOException

startGi

public void startGi(Rcb rcb)
             throws ServiceError,
                    java.io.IOException

Throws:

ServiceError

java.io.IOException

setRcbValues

public java.util.List<ServiceError> setRcbValues(Rcb rcb,
                                                 boolean setRptId,
                                                 boolean setDatSet,
                                                 boolean setOptFlds,
                                                 boolean setBufTm,
                                                 boolean setTrgOps,
                                                 boolean setIntgPd,
                                                 boolean setPurgeBuf,
                                                 boolean setEntryId)
                                          throws java.io.IOException

Sets the selected values of the given report control block. Note that all these parameters may only be set if the RCB has been reserved but reporting has not been enabled yet.

The data set reference as it is set in an RCB must contain a dollar sign instead of a dot to separate the logical node from the data set name, e.g.: 'LDevice1/LNode$DataSetName'. Therefore his method will check the reference for a dot and if necessary convert it to a '$' sign before sending the request to the server.

The parameters PurgeBuf, EntryId are only applicable if the given rcb is of type BRCB.

Parameters:

rcb - the report control block

setRptId - whether to set the report ID

setDatSet - whether to set the data set

setOptFlds - whether to set the optional fields

setBufTm - whether to set the buffer time

setTrgOps - whether to set the trigger options

setIntgPd - whether to set the integrity period

setPurgeBuf - whether to set purge buffer

setEntryId - whether to set the entry ID

Returns:

a list indicating ServiceErrors that may have occurred.

Throws:

java.io.IOException - if a fatal IO error occurs. The association object will be closed and can no longer be used after this exception is thrown.

select

public boolean select(FcModelNode controlDataObject)
               throws ServiceError,
                      java.io.IOException

Performs the Select ACSI Service of the control model on the given controllable Data Object (DO). By selecting a controllable DO you can reserve it for exclusive control/operation. This service is only applicable if the ctlModel Data Attribute is set to "sbo-with-normal-security" (2).

The selection is canceled in one of the following events:

• The "Cancel" ACSI service is issued.
• The sboTimemout (select before operate timeout) runs out. If the given controlDataObject contains a sboTimeout Data Attribute it is possible to change the timeout after which the selection/reservation is automatically canceled by the server. Otherwise the timeout is a local issue of the server.
• The connection to the server is closed.
• An operate service failed because of some error
• The sboClass is set to "operate-once" then the selection is also canceled after a successful operate service.

Parameters:

controlDataObject - needs to be a controllable Data Object that contains a Data Attribute named "SBO".

Returns:

false if the selection/reservation was not successful (because it is already selected by another client). Otherwise true is returned.

Throws:

ServiceError - if a ServiceError is returned by the server.

java.io.IOException - if a fatal IO error occurs. The association object will be closed and can no longer be used after this exception is thrown.

operate

public void operate(FcModelNode controlDataObject)
             throws ServiceError,
                    java.io.IOException

Executes the Operate ACSI Service on the given controllable Data Object (DO). The following subnodes of the given control DO should be set according your needs before calling this function. (Note that you can probably leave most attributes with their default value):

• Oper.ctlVal - has to be set to actual control value that is to be written using the operate service.
• Oper.operTm (type: BdaTimestamp) - is an optional sub data attribute of Oper (thus it may not exist). If it exists it can be used to set the timestamp when the operation shall be performed by the server. Thus the server will delay execution of the operate command until the given date is reached. Can be set to an empty byte array (new byte[0]) or null so that the server executes the operate command immediately. This is also the default.
• Oper.check (type: BdaCheck) is used to tell the server whether to perform the synchrocheck and interlockcheck. By default they are turned off.
• Oper.orign - contains the two data attributes orCat (origin category, type: BdaInt8) and orIdent (origin identifier, type BdaOctetString). Origin is optionally reflected in the status Data Attribute controlDO.origin. By reading this data attribute other clients can see who executed the last operate command. The default value for orCat is 0 ("not-supported") and the default value for orIdent is ""(the empty string).
• Oper.Test (BdaBoolean) - if true this operate command is sent for test purposes only. Default is false.

All other operate parameters are automatically handled by this function.

Parameters:

controlDataObject - needs to be a controllable Data Object that contains a Data Attribute named "Oper".

Throws:

ServiceError - if a ServiceError is returned by the server

java.io.IOException - if a fatal IO error occurs. The association object will be closed and can no longer be used after this exception is thrown.

isOpen

public boolean isOpen()

close

public void close()

Will close the connection simply by closing the TCP socket.

disconnect

public void disconnect()

Will send a disconnect request first and then close the TCP socket.