Implementing Registered Interfaces

After you have registered the interface, implement it in the providing application. The providing application must implement the interface accurately so that the consumer application does not encounter any unexpected behavior.

These topics discuss how to:

  • Implement types.

  • Implement services.

  • Implement exceptions.

  • Implement SQLViews.

To implement a registered type interface:

Note: Implement registered types as PeopleCode application classes.

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

    Use the first level sub-package to group implementation classes by function and the second level to group classes by versions.

  2. Create the application class that is implementing the interface type.

    When you create the application class, you must ensure that it:

    • Extends the baseType class.

    • Imports the package with the baseType parent class definition.

    • Exposes a read-only property IUD with the type string.

    • Has a IUD property that contains the correct IUD of the corresponding registry entry.

    • Instantiates any array properties defined in the class as array properties with 0 elements.

    • Implements the following mandatory public methods: toXmlNode, toXmlNodeString, fromXmlNode, and truncateType.

  3. Copy the stub code the system created when you clicked the Generate Class Code button on the Registry Wizard - Implementation page for this interface and paste it into the application class implementing the interface type.

    The generated type stub code includes the following mandatory methods:

    method toxmlNode(&parentNode As XmlNode);
    method fromXmlNode(&parentNode As XmlNode);
    method toXmlNodeString(&nodeName As string) Returns string;
    method TruncateType();

    The system uses the XML mandatory methods to marshal and unmarshal the type to or from an xml representation, which is required in order to use this type in a remote service invocation. The truncateType mandatory method resents the value of all type elements.

  4. Access the registry entry for the type interface in the Registry Wizard and add the application class to the type's implementation details.

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.

PeopleSoft delivers a baseException class providing the default exception handling, which is on the PeopleTools exception class. The baseException class constructor takes the following parameters:

  • An instance of a service log.

  • A message set number and message number.

  • Default message text.

  • Message parameters 1–5 or "Null" when none.

The base Exception class constructor executes the following logic:

  • Adds PSMessages collection to the service log.

  • Creates a PeopleTools exception for the provided message set and message number.

To implement a registered type interface:

Note: Implement registered exceptions as PeopleCode application classes.

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

    Use the first level sub-package to group implementation classes by function and the second level to group classes by versions.

  2. Copy the stub code the system created when you clicked the Generate Class Code button on the Registry Wizard - Implementation page for this interface and paste it into the application class implementing the exception.

  3. Confirm that the exception implementation contains the following:

    • A link to an entry in the PeopleTools message catalog.

    • Default error processing.

    • Exception-specific error processing, where necessary.

    Note: The exception's registry entry defines the exception name, the fault message structure, and the exception semantics (description).

  4. Confirm that the implementation of the exception class:

    • Name is identical to the registry entry name.

    • Extends the baseException and import the baseException class definition.

    • Contains a constructor that:

      — Takes an instance of a LogType as a single parameter and imports the LogType class definition.

      — Facilitates the default error processing by wan of an instance of a parent class.

      — Assigns the correct IUD of the corresponding registry entry to its IUD property.

    • Exposes a read-only property IUD with a type of string.

To implement a registered sqlView interface:

Note: Implement registered sqlView interfaces as PeopleSoft record definitions with a type of view.

  1. Create fields on the record definition to correspond to each field in the registered sqlView interface.

  2. Run SQL Create to create the view in the database.

  3. Open the sqlView registry entry and add the implementation record name to the registry entry.

    When you are creating a new interface view, you must use the Registry Wizard component. When you are updating an existing view, you must use access the registry and click the Update button. The system then displays the Registry Wizard component.

    See Registering New Interfaces.