org.openmuc.openiec61850

## Class ClientAssociation

- java.lang.Object
- - org.openmuc.openiec61850.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

All Methods Instance Methods Concrete Methods
`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` `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.
`ServerModel` `getModelFromSclFile(java.lang.String sclFilePath)` Parses the given SCL File and returns the server model that is described by it.
`void` `getRcbValues(Rcb rcb)`
`int` `getResponseTimeout()` Gets the response timeout.
`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` `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 were returned by the retrieveModel() or getModelFromSclFile() functions.

### Methods inherited from class java.lang.Object

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

### Method Detail

#### 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.

#### 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.

#### getModelFromSclFile

    public ServerModel getModelFromSclFile(java.lang.String sclFilePath)
                                    throws SclParseException

Parses the given SCL File and returns the server model that is described by it. This function can be used instead of `retrieveModel` in order to get the server model that is needed to call the other ACSI services.

Parameters:
  `sclFilePath` - the path to the SCL file that is to be parsed.
Returns:
  The ServerNode that is the root node of the complete server model.
Throws:
  `SclParseException` - if any kind of fatal error occurs in the parsing process.

#### 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.

#### 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 were returned by the retrieveModel() or getModelFromSclFile() functions. 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 reporting for this report control block is not enabled and if it is not reserved by another client. 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.

#### 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.