Implementing Services

Consumer programs cannot directly instantiate service implementation classes. Due to late binding and remote procedure call support, the framework delays the resolution of the implementation class name until run-time so the only information available to service consumers during design is the interface name.

At run-time, the service manager resolves the interface name into the implementation class name using the registry lookup functionality. Depending on the implementation details defined in the registry, the service manager will return to the consumer either an instance of a local implementation class or a proxy class for the remote implementation.

Because of these considerations, the providing application needs to supply the following two application classes to fully implement a service:

  • An interface that consumer applications can refer to during design.

  • An implementation class that the service manager can bind to during run-time.

Note:

Implement registered services as PeopleCode application classes.

To implement a registered service interface:

  1. In Application Designer, create an application package for each functional module using the naming convention <NAMESPACE_PREFIX>_SERVICES.

    Use the first level sub-package to group implementation classes by function and the second level to group classes by versions. Use the third (application class) level to define an interface and an implementation for the service.

  2. Create two application classes to implement the service, an interface and an implementation class.

  3. Select the registry entry for this service and click the Generate provider Code button. The system displays a page with three group boxes containing code:

    • Interface PeopleCode

      Copy and paste the interface PeopleCode into the interface application class.

    • Implementation PeopleCode

      Copy and paste the implementation PeopleCode into the implementation application class. The implementation code generated is only a skeleton the actual logic for the application class. The development team must therefore modify the implementation class to meet the providing application's needs.

    • Proxy PeopleCode

  4. Confirm that the interface and implementation classes contain the necessary information.

    The two applications serve different functions. The interface class is an abstract definition and details what methods and properties the implementation class will have to have to comply with registered specifications, but it does not contain the implementation details. The implementation class actually implements the interface, providing the executable code for the abstract method definitions.

    The interface application class must:

    • Have names identical to the name of the registered service.

    • Extend the baseService class.

    • Imports the baseService parent class definition.

    • Contain a constructor method that creates an instance of the parent baseService class.

    • Define an abstract DoService method with the signature matching the signature of the registered service.

  5. Confirm that the implementation of the service:

    • Implements the interface.

    • Provides a concrete implementation of the DoService method.

      When a development team decides to provide a service, they create an interface and implementation class that implements it.

    • Imports the interface that it implements, as well as the types and exceptions it is working with.

      This happens once you generate the provider code.

    • Throws exceptions in accordance with the registered interface contract in order to handle errors.

    • Can log warnings in accordance with the interface contract.

      The interface application class provides details of all warnings that were generated when the service was executed.

    • Uses the API2CI framework to abstract from the component interface specifics, if the implementation is component interface-based.

      Component interface-based services need to import the CI library (which is provided with the registry) using this code: 

      import HMCR_API2CI

      If you are using a DoService method, you need to declare two local objects: ciHandler and ciIdent. ciHandler is the class managing all access to a component interface since you cannot directly manipulate a component interface. ciIdent defines the unique attributes of each ciHandler instance.

  6. Access the registry entry for the service interface and add the implementation application class to the type's implementation details.

Note:

You can use services to organize multiple other services to execute an business task. This is called aggregating services. The aggregating service is the service responsible for managing the business transaction, housekeeping, and performing the save professing so these processes are run only once, improving overall performance. When a service is running another service in aggregation mode, the calling service (the aggregating service) sets the RunAggregated flag on the called service, causing the called service to skip the housekeeping and save processing.