org.openmuc.openiec61850
Class ClientAssociation

java.lang.Object
  extended by 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
 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 nonpersistent 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)
           
 Report getReport()
           
 Report getReport(int timeout)
           
 int getResponseTimeout()
          Gets the response timeout.
 void operate(FcModelNode controlDataObject)
          Executes the Operate ACSI Service on the given controllable Data Object (DO).
 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, boolean setResvTms)
          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() function.
 
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 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 any kind of fatal association error occurred.

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 any kind of fatal association error occurred.

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 say 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 any kind of fatal association error occurs.

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() function. It will delete DataSets that have been deleted since the last update and add any new DataSets

Throws:
ServiceError
java.io.IOException

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 nonpersistent list or to the model. Then it should call this method for creation on the server side

Throws:
ServiceError
java.io.IOException

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:
ServiceError
java.io.IOException

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

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,
                                                 boolean setResvTms)
                                          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 and ResvTms are only applicable if the given rcb is of type BRCB.

Parameters:
rcb -
setRptId -
setDatSet -
setOptFlds -
setBufTm -
setTrgOps -
setIntgPd -
setPurgeBuf -
setEntryId -
setResvTms -
Returns:
a list indicating ServiceErrors that may have occurred.
Throws:
java.io.IOException

getReport

public Report getReport()
                 throws ServiceError
Throws:
ServiceError

getReport

public Report getReport(int timeout)
                 throws ServiceError
Throws:
ServiceError

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:

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
java.io.IOException

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): 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
java.io.IOException

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.