org.csapi.jr.se.fw.fw_service.service_registration
Interface FwServiceRegistration

All Superinterfaces:
CsapiInterface, java.io.Serializable

public interface FwServiceRegistration
extends CsapiInterface

The Service Registration interface provides the methods used for the registration of network SCFs at the framework. This interface and at least the methods registerService(), announceServiceAvailability(), unregisterService() and unannounceService() shall be implemented by a Framework.


Method Summary
 void announceServiceAvailability(java.lang.String serviceID, org.csapi.jr.se.fw.fw_service.service_lifecycle.ServiceInstanceLifecycleManager serviceInstanceLifecycleManagerRef)
          The registerService() method described previously does not make the service discoverable.
 org.csapi.jr.se.fw.ServiceDescription describeService(java.lang.String serviceID)
          The describeService() operation returns the information about a service that is registered in the framework.
 java.lang.String registerService(java.lang.String serviceTypeName, org.csapi.jr.se.fw.ServiceProperty[] servicePropertyList)
          The registerService() operation is the means by which a service is registered in the Framework, for subsequent discovery by the enterprise applications.
 java.lang.String registerServiceSubType(java.lang.String serviceTypeName, org.csapi.jr.se.fw.ServiceProperty[] servicePropertyList, org.csapi.jr.se.fw.ServiceTypePropertyValue[] extendedServicePropertyList)
          The registerServiceSubType() operation is the means by which an extended service is registered in the Framework, for subsequent discovery by the enterprise applications.
 void unannounceService(java.lang.String serviceID)
          This method results in the service no longer being discoverable by applications.
 void unregisterService(java.lang.String serviceID)
          The unregisterService() operation is used by the service suppliers to remove a registered service from the Framework.
 

Method Detail

registerService

public java.lang.String registerService(java.lang.String serviceTypeName,
                                        org.csapi.jr.se.fw.ServiceProperty[] servicePropertyList)
                                 throws CommonException,
                                        PropertyTypeMismatchException,
                                        DuplicatePropertyNameException,
                                        IllegalServiceTypeException,
                                        UnknownServiceTypeException,
                                        MissingMandatoryPropertyException,
                                        ServiceTypeUnavailableException,
                                        PlatformException
The registerService() operation is the means by which a service is registered in the Framework, for subsequent discovery by the enterprise applications. Registration can only succeed when the Service type of the service is known to the Framework (ServiceType is 'available'). A service-ID is returned to the service supplier when a service is registered in the Framework. When the service is not registered because the ServiceType is 'unavailable', a P_SERVICE_TYPE_UNAVAILABLE is raised. The service-ID is the handle with which the service supplier can identify the registered service when needed (for example for withdrawing it). The service-ID is only meaningful in the context of the Framework that generated it. This method should be used for registration of service super types only. For registering service sub types, the registerServiceSubType() method should be used. Returns : This is the unique handle that is returned as a result of the successful completion of this operation. The Service Supplier can identify the registered service when attempting to access it via other operations such as unregisterService(), etc. Enterprise client applications are also returned this service-ID when attempting to discover a service of this type. If a service is registered with the property P_COMPATIBLE_WITH_SERVICE in its servicePropertyList, then the Framework shall notify all applications using instances of services identified by this property, using the P_EVENT_FW_MIGRATION_SERVICE_AVAILABLE event, if they have registered for such a notification. If an incorrect combination of properties is included in conjunction with P_COMPATIBLE_WITH_SERVICE, a P_MISSING_MANDATORY_PROPERTY exception is raised.

Parameters:
serviceTypeName - The "serviceTypeName" parameter identifies the service type. If the string representation of the "type" does not obey the rules for identifiers, then a P_ILLEGAL_SERVICE_TYPE exception is raised. If the "type" is correct syntactically but the Framework is able to unambiguously determine that it is not a recognised service type, then a P_UNKNOWN_SERVICE_TYPE exception is raised.
servicePropertyList - The "servicePropertyList" parameter is a list of property name and property value pairs. They describe the service being registered. This description typically covers behavioural, non-functional and non-computational aspects of the service. Service properties are marked "mandatory" or "readonly". These property mode attributes have the following semantics: a. mandatory - a service associated with this service type must provide an appropriate value for this property when registering. b. readonly - this modifier indicates that the property is optional, but that once given a value, subsequently it may not be modified. Specifying both modifiers indicates that a value must be provided and that subsequently it may not be modified. Examples of such properties are those which form part of a service agreement and hence cannot be modified by service suppliers during the life time of service. If the type or the semantics of the type of any of the property values is not the same as the declared type (declared in the service type), then a P_PROPERTY_TYPE_MISMATCH exception is raised. If the "servicePropertyList" parameter omits any property declared in the service type with a mode of mandatory, then a P_MISSING_MANDATORY_PROPERTY exception is raised. If two or more properties with the same property name are included in this parameter, the P_DUPLICATE_PROPERTY_NAME exception is raised.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
PropertyTypeMismatchException - Property Type Mismatch
DuplicatePropertyNameException - A duplicate property name has been received
IllegalServiceTypeException - Illegal Service Type
UnknownServiceTypeException - Unknown Service Type
MissingMandatoryPropertyException - Mandatory Property Missing
ServiceTypeUnavailableException - The service type is not available according to the Framework.
PlatformException - The implementation detected an internal (for example, communication) error

announceServiceAvailability

public void announceServiceAvailability(java.lang.String serviceID,
                                        org.csapi.jr.se.fw.fw_service.service_lifecycle.ServiceInstanceLifecycleManager serviceInstanceLifecycleManagerRef)
                                 throws CommonException,
                                        IllegalServiceIdException,
                                        UnknownServiceIdException,
                                        InvalidInterfaceTypeException,
                                        PlatformException
The registerService() method described previously does not make the service discoverable. The announceServiceAvailability() method is invoked after the service is authenticated and its service instance lifecycle manager is instantiated at a particular interface. This method informs the framework of the availability of "service instance lifecycle manager" of the previously registered service, identified by its service ID, at a specific interface. After the receipt of this method, the framework makes the corresponding service discoverable. There exists a "service manager" instance per service instance. Each service implements the IpServiceInstanceLifecycleManager interface. The IpServiceInstanceLifecycleManager interface supports a method called the createServiceManager(application: in TpClientAppID, serviceProperties : in TpServicePropertyList, serviceInstanceID : in TpServiceInstanceID) : IpServiceRef. When the service agreement is signed for some serviceID (using signServiceAgreement()), the framework calls the createServiceManager() for this service, gets a serviceManager and returns this to the client application.

Parameters:
serviceID - The service ID of the service that is being announced. If the string representation of the "serviceID" does not obey the rules for service identifiers, then a P_ILLEGAL_SERVICE_ID exception is raised. If the "serviceID" is legal but there is no service offer within the Framework with that ID, then a P_UNKNOWN_SERVICE_ID exception is raised.
serviceInstanceLifecycleManagerRef - The interface reference at which the service instance lifecycle manager of the previously registered service is available.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
IllegalServiceIdException - Illegal Service ID
UnknownServiceIdException - Unknown Service ID
InvalidInterfaceTypeException - The interface reference supplied by the client is the wrong type.
PlatformException - The implementation detected an internal (for example, communication) error

unregisterService

public void unregisterService(java.lang.String serviceID)
                       throws CommonException,
                              IllegalServiceIdException,
                              UnknownServiceIdException,
                              PlatformException
The unregisterService() operation is used by the service suppliers to remove a registered service from the Framework. The service is identified by the "service-ID" which was originally returned by the Framework in response to the registerService() operation. The service must be in the SCF Registered state. All instances of the service will be deleted.

Parameters:
serviceID - The service to be withdrawn is identified by the "serviceID" parameter which was originally returned by the registerService() operation. If the string representation of the "serviceID" does not obey the rules for service identifiers, then a P_ILLEGAL_SERVICE_ID exception is raised. If the "serviceID" is legal but there is no service offer within the Framework with that ID, then a P_UNKNOWN_SERVICE_ID exception is raised.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
IllegalServiceIdException - Illegal Service ID
UnknownServiceIdException - Unknown Service ID
PlatformException - The implementation detected an internal (for example, communication) error

describeService

public org.csapi.jr.se.fw.ServiceDescription describeService(java.lang.String serviceID)
                                                      throws CommonException,
                                                             IllegalServiceIdException,
                                                             UnknownServiceIdException,
                                                             PlatformException
The describeService() operation returns the information about a service that is registered in the framework. It comprises, the "type" of the service , and the "properties" that describe this service. The service is identified by the "service-ID" parameter which was originally returned by the registerService() operation. The SCS may register various versions of the same SCF, each with a different description (more or less restrictive, for example), and each getting a different serviceID assigned. Returns : This consists of the information about an offered service that is held by the Framework. It comprises the "type" of the service , and the properties that describe this service.

Parameters:
serviceID - The service to be described is identified by the "serviceID" parameter which was originally returned by the registerService() operation. If the string representation of the "serviceID" does not obey the rules for object identifiers, then an P_ILLEGAL_SERVICE_ID exception is raised. If the "serviceID" is legal but there is no service offer within the Framework with that ID, then a P_UNKNOWN_SERVICE_ID exception is raised.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
IllegalServiceIdException - Illegal Service ID
UnknownServiceIdException - Unknown Service ID
PlatformException - The implementation detected an internal (for example, communication) error

unannounceService

public void unannounceService(java.lang.String serviceID)
                       throws CommonException,
                              IllegalServiceIdException,
                              UnknownServiceIdException,
                              PlatformException
This method results in the service no longer being discoverable by applications. It is, however, still registered and the service ID is still associated with it. Applications currently using the service can continue to use the service but no new applications should be able to start using the service. Also, all unused service tokens relating to the service will be expired. This will prevent anyone who has already performed a selectService() but not yet performed the signServiceAgreement() from being able to obtain a new instance of the service.

Parameters:
serviceID - The service ID of the service that is being unannounced. If the string representation of the "serviceID" does not obey the rules for service identifiers, then an P_ILLEGAL_SERVICE_ID exception is raised. If the "serviceID" is legal but there is no service offer within the Framework with that ID, then an P_UNKNOWN_SERVICE_ID exception is raised.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
IllegalServiceIdException - Illegal Service ID
UnknownServiceIdException - Unknown Service ID
PlatformException - The implementation detected an internal (for example, communication) error

registerServiceSubType

public java.lang.String registerServiceSubType(java.lang.String serviceTypeName,
                                               org.csapi.jr.se.fw.ServiceProperty[] servicePropertyList,
                                               org.csapi.jr.se.fw.ServiceTypePropertyValue[] extendedServicePropertyList)
                                        throws CommonException,
                                               PropertyTypeMismatchException,
                                               DuplicatePropertyNameException,
                                               IllegalServiceTypeException,
                                               UnknownServiceTypeException,
                                               MissingMandatoryPropertyException,
                                               ServiceTypeUnavailableException,
                                               PlatformException
The registerServiceSubType() operation is the means by which an extended service is registered in the Framework, for subsequent discovery by the enterprise applications. Registration only succeeds if the service type is known to the Framework (ServiceType is 'available'). A service-ID is returned to the service supplier when a service is registered in the Framework. When the service is not registered because the ServiceType is 'unavailable', a P_SERVICE_TYPE_UNAVAILABLE exception is raised. The service-ID is the handle with which the service supplier can identify the registered service when needed (for example for withdrawing it). The service-ID is only meaningful in the context of the Framework that generated it. This method should be used for registration of service sub types only. For registering service super types, the registerService () method should be used. Returns : This is the unique handle that is returned as a result of the successful completion of this operation. The Service Supplier can identify the registered service when attempting to access it via other operations such as unregisterService(), etc. Enterprise client applications are also returned this service-ID when attempting to discover a service of this type.

Parameters:
serviceTypeName - The "serviceTypeName" parameter identifies the service type. If the string representation of the "type" does not obey the rules for identifiers, then a P_ILLEGAL_SERVICE_TYPE exception is raised. If the "type" is correct syntactically but the Framework is able to unambiguously determine that it is not a recognised service type, then a P_UNKNOWN_SERVICE_TYPE exception is raised.
servicePropertyList - The "servicePropertyList" parameter is a list of property name and property value pairs corresponding to the service properties applicable to the standard service. They describe the service being registered. If the type or the semantics of the type of any of the property values is not the same as the declared type (declared in the service type), then a P_PROPERTY_TYPE_MISMATCH exception is raised. If the "servicePropertyList" parameter omits any property declared in the service type with a mode of mandatory, then a P_MISSING_MANDATORY_PROPERTY exception is raised. If two or more properties with the same property name are included in this parameter, the P_DUPLICATE_PROPERTY_NAME exception is raised.
extendedServicePropertyList - The "extendedServicePropertyList" parameter is a list of property name, mode, type, and property value tuples corresponding to the service properties applicable to the extended standard service. They describe the service being registered. If two or more properties with the same property name are included in this parameter, the P_DUPLICATE_PROPERTY_NAME exception is raised.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
PropertyTypeMismatchException - Property Type Mismatch
DuplicatePropertyNameException - A duplicate property name has been received
IllegalServiceTypeException - Illegal Service Type
UnknownServiceTypeException - Unknown Service Type
MissingMandatoryPropertyException - Mandatory Property Missing
ServiceTypeUnavailableException - The service type is not available according to the Framework.
PlatformException - The implementation detected an internal (for example, communication) error