Implementing Callable Objects for Background Execution

Use

You can implement callable objects that do not expose a user interface and are executed in the background, so that their execution remains transparent to the user. For such objects, Guided Procedures (GP) defines a set of Java APIs in package com.sap.caf.eu.gp.api .

The background callable object is deployed on the Java server as an application.

Prerequisites

You have set up your project as described in Setting Up Your Project .

In addition to the required development components, you need to add dependencies to the following DCs in software component ENGFACADE:

  • tc/bl/exception/lib
  • tc/bl/logging/api

Procedure

Implement the Required Interfaces

  1. In the Package Explorer view, create a new class that implements the interface com.sap.caf.eu.gp.co.api.IGPBackgroundCallableObject .
  2. In the Development Infrastructure Perspective, create a new public part using the option Can be packaged into other build results (e.g. SDAs).

    Make sure that you include the whole Java package tree where you have created the Java class in the public part.

  3. Create a new development component project of type J2EE → Enterprise Application.
  4. In the Development Infrastructure Perspective, open the Component Properties of the DC by selecting Show In  → Property View from the context menu and define a build-time dependency to the public part that you created in step 4.
  5. In the Java EE Perspective, in the file application-j2ee-engine.xml, add a reference to the caf/au/gp/api library, with provider sap.com.

For more information about the development components you create, see Creating Development Components (DCs) .

Implement the Design Time Aspects of the Callable Object

For the design-time part of the background callable object, you must implement the getDescription() method of the IGPBackgroundCallableObject interface.

  1. Create the technical description of the object.

    Use the method createTechnicalDescription() of the class com.sap.caf.eu.gp.co.api.GPCallableObjectFactory . As parameters, enter the keys to the localizable name and description of the object, as well as a reference to a resource accessor instance, and the original locale.

  1. Define the input and output parameters.

    They are presented as structure attributes. The GP framework defines a root structure for both input and output.

    Structures have multiplicity and can be nested. To create a sub-structure, you use interface com.sap.caf.eu.gp.co.api.IGPStructureInfo . You add the structure to an existing one using method addStructure() .

    Attributes have multiplicity as well as being of a certain type. To define a parameter, you use the method addAttribute() of the interface com.sap.caf.eu.gp.co.api.IGPTechnicalDescription .

  1. Define the configuration parameters

    A callable object may define string, integer, Boolean, or MIME type configuration parameters. The default type is string. You can create a configuration parameter that exposes a list of predefined values.

    To create a configuration parameter, use the method addConfigurationAttribute() of the interface IGPTechnicalDescription .

  1. Define the result states for completing the callable object's execution.

    You must define at least one result state that you can set when you complete the object's execution. You can define any number of result states, and use them to define the behavior of the callable object in cases of errors. They are also a convenient way of managing process flow at runtime in accordance with the result of the callable object execution.

    To add a result state, use the method addResultState() of the interface IGPTechnicalDescription .

  1. Finally, define process exceptions.

    You may define specific process exceptions for the callable object. They are related to the functionality implemented in the component, and enable you to include the exception processing as a part of the process flow at runtime using the exception handling mechanisms at block level.

Implement the Runtime Logic of the Object

At execution, you read the input and set the output in the execute() method of the IGPBackgroundCallableObject interface, using the com.sap.caf.eu.gp.co.api.IGPExecutionContext interface methods.

  1. To read the input, you get the input structure from the execution context as an instance of IGPStructure interface, and then retrieve the metadata either from the context, or from the structure itself.
  1. To set the output parameters, you get the output structure as an IGPStructure instance, and then set the attribute values.
  1. Finally, set the result state of the execution in the execution context and indicate to the framework that the execution of the callable object has been completed by calling method processingComplete() .
  1. Set up the exception handling mechanisms.

    If you have defined any process exceptions, set them appropriately when completing the process.

    You can also use com.sap.caf.eu.gp.exception.api.GPTechnicalCallableObjectException to indicate errors.

For logging and tracing, use the standard SAP logging APIs. For more information, see the API documentation at http://www.sdn.sap.com/irj/sdn/javadocs.

Implement Localization

All names and descriptions can be localized using a standard Java resource bundle (a text file with the extension .properties). The technical names that you use in the implementation are automatically available as keys, and in addition, you can define other keys where necessary.

  1. To access the texts in Java, create a resource accessor that extends class com.sap.caf.eu.gp.co.api.GPStandardResourceAccessor and calls its constructor with the resource bundle passed as a parameter.
  2. Initialize the resource accessor in your background callable object class.

Result

You can now build your Java Enterprise Application and deploy it to the server.

Next, you must expose the Java class as a callable object in the GP design time. For more information, see Creating Callable Objects for Background Execution .

Example

For an example of a background callable object, see Implementing and Exposing a Background Callable Object .