org.csapi.jr.se.fw.fw_application.integrity
Interface LoadManager

All Superinterfaces:
CsapiInterface, java.io.Serializable

public interface LoadManager
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 client application. 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 IpLoadManager interface. Most methods are asynchronous, in that they do not lock a thread into waiting whilst a transaction performs. To handle responses and reports, the client application developer must implement the IpAppLoadManager interface to provide the callback mechanism. The application supplies the identity of this callback interface at the time it obtains the framework's load manager interface, by use of the obtainInterfaceWithCallback operation on the IpAccess interface. If the IpLoadManager 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 IpAppLoadManager.queryAppLoadStatsReq() method, then it shall implement queryAppLoadStatsRes() and queryAppLoadStatsErr() methods in this interface.


Method Summary
 void createLoadLevelNotification(java.lang.String[] serviceIDs)
          The client application uses this method to register to receive notifications of load level changes associated with either the framework or with its instances of the individual services used by the application.
 void destroyLoadLevelNotification(java.lang.String[] serviceIDs)
          The client application uses this method to unregister for notifications of load level changes associated with either the framework or with its instances of the individual services used by the application.
 void queryAppLoadErr(org.csapi.jr.se.fw.LoadStatisticError loadStatisticsError)
          Deprecated.  
 void queryAppLoadRes(org.csapi.jr.se.fw.LoadStatistic[] loadStatistics)
          Deprecated.  
 void queryAppLoadStatsErr(int loadStatsReqID, org.csapi.jr.se.fw.LoadStatisticError loadStatisticsError)
          The client application uses this method to return an error response to the framework that requested the application's load statistics information, when the application is unsuccessful in obtaining any load statistic records; that is in response to an invocation of the queryAppLoadStatsReq method on the IpAppLoadManager interface.
 void queryAppLoadStatsRes(int loadStatsReqID, org.csapi.jr.se.fw.LoadStatistic[] loadStatistics)
          The client application 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 queryAppLoadStatsReq method on the IpAppLoadManager interface.
 void queryLoadReq(java.lang.String[] serviceIDs, org.csapi.jr.se.TimeInterval timeInterval)
          Deprecated.  
 void queryLoadStatsReq(int loadStatsReqID, java.lang.String[] serviceIDs, org.csapi.jr.se.TimeInterval timeInterval)
          The client application uses this method to request the framework to provide load statistic records for the framework or for its instances of the individual services.
 void reportLoad(org.csapi.jr.se.fw.LoadLevel loadLevel)
          The client application uses this method to report its current load level (0,1, or 2) to the framework: for example when the load level on the application has changed.
 void resumeNotification(java.lang.String[] serviceIDs)
          The client application uses this method to request the framework to resume sending it load management notifications associated with either the framework or with its instances of the individual services used by the application; for example after a period of suspension during which the application handled a temporary overload condition.
 void suspendNotification(java.lang.String[] serviceIDs)
          The client application uses this method to request the framework to suspend sending it load management notifications associated with either the framework or with its instances of the individual services used by the application; for example while the application handles a temporary overload condition.
 

Method Detail

reportLoad

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

Parameters:
loadLevel - Specifies the application'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(java.lang.String[] serviceIDs,
                         org.csapi.jr.se.TimeInterval timeInterval)
                  throws CommonException,
                         InvalidServiceIdException,
                         ServiceNotEnabledException,
                         UnauthorisedParameterValueException,
                         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 client application uses this method to request the framework to provide load statistic records for the framework or for its instances of the individual services. If the application does not have access to a service instance with the specified serviceID, the P_UNAUTHORISED_PARAMETER_VALUE exception shall be thrown. The extraInformation field of the exception shall contain the corresponding serviceID.

Parameters:
serviceIDs - Specifies the framework or the services for which load statistics records should be reported. If this parameter is not an empty list, the load statistics records of the client's instances of the specified services are returned, otherwise the load statistics record of the framework is returned.
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.
InvalidServiceIdException - Invalid service ID
ServiceNotEnabledException - The service ID does not correspond to a service that has been enabled
UnauthorisedParameterValueException - A method parameter value violates the Service Level Agreement.
PlatformException - The implementation detected an internal (for example, communication) error

queryAppLoadRes

public void queryAppLoadRes(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 queryAppLoadStatsRes shall be used instead, using the new identifier to correlate requests and responses. The client application 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 queryAppLoadReq method on the IpAppLoadManager interface.

Parameters:
loadStatistics - Specifies the application-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

queryAppLoadErr

public void queryAppLoadErr(org.csapi.jr.se.fw.LoadStatisticError loadStatisticsError)
                     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 queryAppLoadStatsErr shall be used instead, using the new identifier to correlate requests and errors. The client application uses this method to return an error response to the framework that requested the application's load statistics information, when the application is unsuccessful in obtaining any load statistic records; that is in response to an invocation of the queryAppLoadReq method on the IpAppLoadManager interface.

Parameters:
loadStatisticsError - Specifies the error code associated with the failed attempt to retrieve the application'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(java.lang.String[] serviceIDs)
                                 throws CommonException,
                                        InvalidServiceIdException,
                                        UnauthorisedParameterValueException,
                                        PlatformException
The client application uses this method to register to receive notifications of load level changes associated with either the framework or with its instances of the individual services used by the application. If the application does not have access to a service instance with the specified serviceID, the P_UNAUTHORISED_PARAMETER_VALUE exception shall be thrown. The extraInformation field of the exception shall contain the corresponding serviceID. Upon receipt of this method the framework shall inform the client application of the current framework or service instance load using the loadLevelNotification method on the corresponding IpAppLoadManager.

Parameters:
serviceIDs - Specifies the framework or SCFs to be registered for load control. To register for framework load control, the serviceIDs parameter must be an empty list.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
InvalidServiceIdException - Invalid service ID
UnauthorisedParameterValueException - A method parameter value violates the Service Level Agreement.
PlatformException - The implementation detected an internal (for example, communication) error

destroyLoadLevelNotification

public void destroyLoadLevelNotification(java.lang.String[] serviceIDs)
                                  throws CommonException,
                                         InvalidServiceIdException,
                                         UnauthorisedParameterValueException,
                                         PlatformException
The client application uses this method to unregister for notifications of load level changes associated with either the framework or with its instances of the individual services used by the application. If the application does not have access to a service instance with the specified serviceID, the P_UNAUTHORISED_PARAMETER_VALUE exception shall be thrown. The extraInformation field of the exception shall contain the corresponding serviceID.

Parameters:
serviceIDs - Specifies the framework or the services for which load level changes should no longer be reported. To unregister for framework load control, the serviceIDs parameter must be an empty list.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
InvalidServiceIdException - Invalid service ID
UnauthorisedParameterValueException - A method parameter value violates the Service Level Agreement.
PlatformException - The implementation detected an internal (for example, communication) error

resumeNotification

public void resumeNotification(java.lang.String[] serviceIDs)
                        throws CommonException,
                               InvalidServiceIdException,
                               ServiceNotEnabledException,
                               UnauthorisedParameterValueException,
                               PlatformException
The client application uses this method to request the framework to resume sending it load management notifications associated with either the framework or with its instances of the individual services used by the application; for example after a period of suspension during which the application handled a temporary overload condition. If the application does not have access to a service instance with the specified serviceID, the P_UNAUTHORISED_PARAMETER_VALUE exception shall be thrown. The extraInformation field of the exception shall contain the corresponding serviceID. Upon receipt of this method the framework shall inform the client application of the current framework or service instance load using the loadLevelNotification method on the corresponding IpAppLoadManager.

Parameters:
serviceIDs - Specifies the framework or the services for which the sending of notifications of load level changes by the framework should be resumed. To resume notifications for the framework, the serviceIDs parameter must be an empty list.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
InvalidServiceIdException - Invalid service ID
ServiceNotEnabledException - The service ID does not correspond to a service that has been enabled
UnauthorisedParameterValueException - A method parameter value violates the Service Level Agreement.
PlatformException - The implementation detected an internal (for example, communication) error

suspendNotification

public void suspendNotification(java.lang.String[] serviceIDs)
                         throws CommonException,
                                InvalidServiceIdException,
                                ServiceNotEnabledException,
                                UnauthorisedParameterValueException,
                                PlatformException
The client application uses this method to request the framework to suspend sending it load management notifications associated with either the framework or with its instances of the individual services used by the application; for example while the application handles a temporary overload condition. If the application does not have access to a service instance with the specified serviceID, the P_UNAUTHORISED_PARAMETER_VALUE exception shall be thrown. The extraInformation field of the exception shall contain the corresponding serviceID.

Parameters:
serviceIDs - Specifies the framework or the services for which the sending of notifications by the framework should be suspended. To suspend notifications for the framework, the serviceIDs parameter must be an empty list.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
InvalidServiceIdException - Invalid service ID
ServiceNotEnabledException - The service ID does not correspond to a service that has been enabled
UnauthorisedParameterValueException - A method parameter value violates the Service Level Agreement.
PlatformException - The implementation detected an internal (for example, communication) error

queryLoadStatsReq

public void queryLoadStatsReq(int loadStatsReqID,
                              java.lang.String[] serviceIDs,
                              org.csapi.jr.se.TimeInterval timeInterval)
                       throws CommonException,
                              InvalidServiceIdException,
                              ServiceNotEnabledException,
                              UnauthorisedParameterValueException,
                              PlatformException
The client application uses this method to request the framework to provide load statistic records for the framework or for its instances of the individual services. If the application does not have access to a service instance with the specified serviceID, the P_UNAUTHORISED_PARAMETER_VALUE exception shall be thrown. The extraInformation field of the exception shall contain the corresponding serviceID.

Parameters:
loadStatsReqID - The identifier provided by the application to correlate the response (when it arrives) with this request.
serviceIDs - Specifies the framework or the services for which load statistics records should be reported. If this parameter is not an empty list, the load statistics records of the client's instances of the specified services are returned, otherwise the load statistics record of the framework is returned.
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.
InvalidServiceIdException - Invalid service ID
ServiceNotEnabledException - The service ID does not correspond to a service that has been enabled
UnauthorisedParameterValueException - A method parameter value violates the Service Level Agreement.
PlatformException - The implementation detected an internal (for example, communication) error

queryAppLoadStatsRes

public void queryAppLoadStatsRes(int loadStatsReqID,
                                 org.csapi.jr.se.fw.LoadStatistic[] loadStatistics)
                          throws CommonException,
                                 PlatformException
The client application 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 queryAppLoadStatsReq method on the IpAppLoadManager interface.

Parameters:
loadStatsReqID - Used by the framework to correlate this response (when it arrives) with the original request.
loadStatistics - Specifies the application-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

queryAppLoadStatsErr

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

Parameters:
loadStatsReqID - Used by the framework to correlate this error (when it arrives) with the original request.
loadStatisticsError - Specifies the error code associated with the failed attempt to retrieve the application'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