org.csapi.jr.se.fw.fw_service.integrity
Interface FwLoadManager

All Superinterfaces:
CsapiInterface, java.io.Serializable

public interface FwLoadManager
extends CsapiInterface

The framework API should allow the load to be distributed across multiple machines and across multiple component processes, according to a load management policy. The separation of the load management mechanism and load management policy ensures the flexibility of the load management services. The load management policy identifies what load management rules the framework should follow for the specific service. It might specify what action the framework should take as the congestion level changes. For example, some real-time critical applications will want to make sure continuous service is maintained, below a given congestion level, at all costs, whereas other services will be satisfied with disconnecting and trying again later if the congestion level rises. Clearly, the load management policy is related to the QoS level to which the application is subscribed. The framework load management function is represented by the IpFwLoadManager interface. To handle responses and reports, the service developer must implement the IpSvcLoadManager interface to provide the callback mechanism. If the IpFwLoadManager interface is implemented by a Framework, at least one of the methods shall be implemented as a minimum requirement. If load level notifications are supported, the createLoadLevelNotification() and destroyLoadLevelNotification() methods shall be implemented. If suspendNotification() is implemented, then resumeNotification() shall be implemented also. If a Framework is capable of invoking the IpSvcLoadManager.querySvcLoadStatsReq() method, then it shall implement querySvcLoadStatsRes() and querySvcLoadStatsErr() methods in this interface.


Method Summary
 void createLoadLevelNotification(org.csapi.jr.se.fw.SubjectType notificationSubject)
          The service instance uses this method to register to receive notifications of load level changes associated with the framework or with the application that uses the service instance.
 void destroyLoadLevelNotification(org.csapi.jr.se.fw.SubjectType notificationSubject)
          The service instance uses this method to unregister for notifications of load level changes associated with the framework or with the application that uses the service instance.
 void queryLoadReq(org.csapi.jr.se.fw.SubjectType querySubject, org.csapi.jr.se.TimeInterval timeInterval)
          Deprecated.  
 void queryLoadStatsReq(int loadStatsReqID, org.csapi.jr.se.fw.SubjectType querySubject, org.csapi.jr.se.TimeInterval timeInterval)
          The service instance uses this method to request the framework to provide load statistics records for the framework or for the application that uses the service instance.
 void querySvcLoadErr(org.csapi.jr.se.fw.LoadStatisticError loadStatisticError)
          Deprecated.  
 void querySvcLoadRes(org.csapi.jr.se.fw.LoadStatistic[] loadStatistics)
          Deprecated.  
 void querySvcLoadStatsErr(int loadStatsReqID, org.csapi.jr.se.fw.LoadStatisticError loadStatisticError)
          The service instance uses this method to return an error response to the framework that requested the service instance's load statistics information, when the service instance is unsuccessful in obtaining any load statistic records; that is in response to an invocation of the querySvcLoadStatsReq method on the IpSvcLoadManager interface.
 void querySvcLoadStatsRes(int loadStatsReqID, org.csapi.jr.se.fw.LoadStatistic[] loadStatistics)
          The service instance uses this method to send load statistic records back to the framework that requested the information; that is in response to an invocation of the querySvcLoadStatsReq method on the IpSvcLoadManager interface.
 void reportLoad(org.csapi.jr.se.fw.LoadLevel loadLevel)
          The service instance uses this method to report its current load level (0,1, or 2) to the framework: for example when the load level on the service instance has changed.
 void resumeNotification(org.csapi.jr.se.fw.SubjectType notificationSubject)
          The service instance uses this method to request the framework to resume sending it notifications associated with the framework or with the application that uses the service instance; for example after a period of suspension during which the service instance handled a temporary overload condition.
 void suspendNotification(org.csapi.jr.se.fw.SubjectType notificationSubject)
          The service instance uses this method to request the framework to suspend sending it notifications associated with the framework or with the application that uses the service instance; for example while the service instance handles a temporary overload condition.
 

Method Detail

reportLoad

public void reportLoad(org.csapi.jr.se.fw.LoadLevel loadLevel)
                throws CommonException,
                       PlatformException
The service instance uses this method to report its current load level (0,1, or 2) to the framework: for example when the load level on the service instance has changed. At level 0 load, the service instance is performing within its load specifications (that is it is not congested or overloaded). At level 1 load, the service instance is overloaded. At level 2 load, the service instance is severely overloaded. In addition this method shall be called by the service instance in order to report current load status, when load notifications are first requested, or resumed after suspension.

Parameters:
loadLevel - Specifies the service instance's load level.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
PlatformException - The implementation detected an internal (for example, communication) error

queryLoadReq

public void queryLoadReq(org.csapi.jr.se.fw.SubjectType querySubject,
                         org.csapi.jr.se.TimeInterval timeInterval)
                  throws CommonException,
                         PlatformException
Deprecated.  

This method is deprecated and will be removed in a later release. It is strongly recommended not to implement this method. The new method queryLoadStatsReq shall be used instead, using the new identifier to correlate requests and responses. The service instance uses this method to request the framework to provide load statistics records for the framework or for the application that uses the service instance.

Parameters:
querySubject - Specifies the entity (framework or application) for which load statistics records should be reported.
timeInterval - Specifies the time interval for which load statistics records should be reported.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
PlatformException - The implementation detected an internal (for example, communication) error

querySvcLoadRes

public void querySvcLoadRes(org.csapi.jr.se.fw.LoadStatistic[] loadStatistics)
                     throws CommonException,
                            PlatformException
Deprecated.  

This method is deprecated and will be removed in a later release. It is strongly recommended not to implement this method. The new method querySvcLoadStatsRes shall be used instead, using the new identifier to correlate requests and responses. The service instance uses this method to send load statistic records back to the framework that requested the information; that is in response to an invocation of the querySvcLoadReq method on the IpSvcLoadManager interface.

Parameters:
loadStatistics - Specifies the service-supplied load statistics.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
PlatformException - The implementation detected an internal (for example, communication) error

querySvcLoadErr

public void querySvcLoadErr(org.csapi.jr.se.fw.LoadStatisticError loadStatisticError)
                     throws CommonException,
                            PlatformException
Deprecated.  

This method is deprecated and will be removed in a later release. It is strongly recommended not to implement this method. The new method querySvcLoadStatsErr shall be used instead, using the new identifier to correlate requests and errors. The service instance uses this method to return an error response to the framework that requested the service instance's load statistics information, when the service instance is unsuccessful in obtaining any load statistic records; that is in response to an invocation of the querySvcLoadReq method on the IpSvcLoadManager interface.

Parameters:
loadStatisticError - Specifies the error code associated with the failed attempt to retrieve the service instance's load statistics.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
PlatformException - The implementation detected an internal (for example, communication) error

createLoadLevelNotification

public void createLoadLevelNotification(org.csapi.jr.se.fw.SubjectType notificationSubject)
                                 throws CommonException,
                                        PlatformException
The service instance uses this method to register to receive notifications of load level changes associated with the framework or with the application that uses the service instance. Upon receipt of this method the framework shall inform the service instance of the current framework or application load using the loadLevelNotification method on the corresponding IpSvcLoadManager.

Parameters:
notificationSubject - Specifies the entity (framework or application) for which load level changes should be reported.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
PlatformException - The implementation detected an internal (for example, communication) error

destroyLoadLevelNotification

public void destroyLoadLevelNotification(org.csapi.jr.se.fw.SubjectType notificationSubject)
                                  throws CommonException,
                                         PlatformException
The service instance uses this method to unregister for notifications of load level changes associated with the framework or with the application that uses the service instance.

Parameters:
notificationSubject - Specifies the entity (framework or application) for which load level changes should no longer be reported.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
PlatformException - The implementation detected an internal (for example, communication) error

suspendNotification

public void suspendNotification(org.csapi.jr.se.fw.SubjectType notificationSubject)
                         throws CommonException,
                                PlatformException
The service instance uses this method to request the framework to suspend sending it notifications associated with the framework or with the application that uses the service instance; for example while the service instance handles a temporary overload condition.

Parameters:
notificationSubject - Specifies the entity (framework or application) for which the sending of notifications by the framework should be suspended.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
PlatformException - The implementation detected an internal (for example, communication) error

resumeNotification

public void resumeNotification(org.csapi.jr.se.fw.SubjectType notificationSubject)
                        throws CommonException,
                               PlatformException
The service instance uses this method to request the framework to resume sending it notifications associated with the framework or with the application that uses the service instance; for example after a period of suspension during which the service instance handled a temporary overload condition. Upon receipt of this method the framework shall inform the service instance of the current framework or application load using the loadLevelNotification method on the corresponding IpSvcLoadManager.

Parameters:
notificationSubject - Specifies the entity (framework or application) for which the sending of notifications of load level changes by the framework should be resumed.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
PlatformException - The implementation detected an internal (for example, communication) error

queryLoadStatsReq

public void queryLoadStatsReq(int loadStatsReqID,
                              org.csapi.jr.se.fw.SubjectType querySubject,
                              org.csapi.jr.se.TimeInterval timeInterval)
                       throws CommonException,
                              PlatformException
The service instance uses this method to request the framework to provide load statistics records for the framework or for the application that uses the service instance.

Parameters:
loadStatsReqID - The identifier provided by the service instance to correlate the response (when it arrives) with this request.
querySubject - Specifies the entity (framework or application) for which load statistics records should be reported.
timeInterval - Specifies the time interval for which load statistics records should be reported.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
PlatformException - The implementation detected an internal (for example, communication) error

querySvcLoadStatsRes

public void querySvcLoadStatsRes(int loadStatsReqID,
                                 org.csapi.jr.se.fw.LoadStatistic[] loadStatistics)
                          throws CommonException,
                                 PlatformException
The service instance uses this method to send load statistic records back to the framework that requested the information; that is in response to an invocation of the querySvcLoadStatsReq method on the IpSvcLoadManager interface.

Parameters:
loadStatsReqID - Used by the framework to correlate this response (when it arrives) with the original request.
loadStatistics - Specifies the service-supplied load statistics.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
PlatformException - The implementation detected an internal (for example, communication) error

querySvcLoadStatsErr

public void querySvcLoadStatsErr(int loadStatsReqID,
                                 org.csapi.jr.se.fw.LoadStatisticError loadStatisticError)
                          throws CommonException,
                                 PlatformException
The service instance uses this method to return an error response to the framework that requested the service instance's load statistics information, when the service instance is unsuccessful in obtaining any load statistic records; that is in response to an invocation of the querySvcLoadStatsReq method on the IpSvcLoadManager interface.

Parameters:
loadStatsReqID - Used by the framework to correlate this error (when it arrives) with the original request.
loadStatisticError - Specifies the error code associated with the failed attempt to retrieve the service instance's load statistics.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
PlatformException - The implementation detected an internal (for example, communication) error