Invoking Service Interfaces

Consuming applications invoke service interfaces in four steps:

  1. Import, declare, and create framework classes, service classes, and type classes.

  2. Bind to the service implementation using the Service Manager's LocateService method.

    At runtime, the Service Manager determines the appropriate implemented interface application class and returns an instance of it to the consuming application for invocation as follows:

    1. The import statement in the consumer code indicates which registered interface is required.

    2. The registered interface contains information about which implemented interface class is required.

    3. The Service Manager's LocateService method returns an instance of the implementation class.

      Note:

      The LocateService method requires the service name and the service version in order to bind to the appropriate service.

    The consumer code only needs to know which registered interface it is using. The provider application specifies which implemented class should be returned to the consumer. This enables the provider to make changes to the implemented interface without impacting the consumer.

  3. If you are invoking a type interface, the consumer application needs to set the properties of the type class in the input parameters prior to passing it to the DoService call.

    The type interface registry entry describes the properties of the type class. The consumer can map properties individually from the consuming application to the type class properties.

  4. Invoke the DoService method of the service implementation class, passing the parameters as defined in the service signature.

    The service signature defines the zero or more input and output parameters that need to be passed to the service. Parameters can be simple types (such as string, number, date, or boolean) or complex types defined and registered as types in the interface registry:

    • When the service requires complex types as parameters, the consumer needs to import the type class, declare it as a local variable and instantiate it using the Create instruction.

    • When the service requires simple types, the simple types only need to be declared by the consumer.

  5. Catch and manage exceptions.

    The consumer code must invoke all services within a try-catch block. All code executed in between the try and the catch statement is in a protected area so that any exceptions thrown during service execution will immediately return control to the catch statement in the consumer code. The consuming application can then react to the exception.

    The consumer code can catch specific exceptions or the baseException, which is the parent class to all registered exceptions.

    Note:

    The consuming code should always catch for baseException to catch exceptions not specific to the service.

  6. Analyze the service execution log for relevant information.

    During service execution, the registry framework collects all warnings and messages issued by the provider and exposes them to the consumer as a service execution log. The consumer can query the execution log and take action based on the warnings and messages, if necessary.

    Each service has a property called ExecutionLog. The property has an array of LogType called Log. The LogType has the following attributes:

    • DEFAULT_TEXT

    • MESSAGE_SET_NBR

    • MESSAGE_NBR

    • MESSAGE_SEVERITY

    The service's Log class has a generic method ShowLog() to display the content of the execution log.

Note:

All consumer PeopleCode runs within the scope of a consumer component session. Any services that the system invokes during the component runtime will also run within this transaction scope. If the service execution encounters fatal errors, the system will roll back the entire component transaction unless the errors are specifically caught as exceptions. For example, if the a component in the consumer application uses two services invoked by the SavePostChange PeopleCode and one executes successfully while the other throws a fatal error, the system will not save any data to the component from either service.