Implementing Callable Objects for Background Execution

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.

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

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 .
   Note

   You must place the implementation for the callable object in the Java DC.

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.

IGPTechnicalDescriptiontechnicalDescription =

         GPCallableObjectFactory.createTechnicalDescription(

            "CO_NAME",

            "CO_DESCRIPTION",

            resourceAccessor,

            originalLocale);

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 .

// the root input structure is preexisting

IGPStructureInfoinput = technicalDescription.getInputStructureInfo();

// add attribute to the root input structure

IGPAttributeInfouserId = input.addAttribute("UserID", IGPAttributeInfo.BASE_STRING);

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 .

IGPConfigAttributeInfoconfigAttribute = technicalDescription.addConfigurationAttribute("ConfigParam");

configAttribute.setOptional(false);

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 .

// add result state with localizable name and description

IGPCOResultStateInfosuccess = technicalDescription.addResultState("Success");

success.setDescriptionKey("Success_desc");

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.

IGPExceptionInfoprocessExc = technicalDescription.addProcessException("USER_NOT_FOUND");

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.

// get the root input structure

IGPStructureinput = executionContext.getInputStructure();

// get a root parameter of type string

StringuserId = (String)input.getAttributeAsString("UserID");

1. To set the output parameters, you get the output structure as an IGPStructure instance, and then set the attribute values.

// get the root output structure

IGPStructureoutput = executionContext.getOutputStructure();

// set attribute value

output.setAttributeValue("firstName",umeUser.getFirstName());

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() .

executionContext.setResultState("Success");

executionContext.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.

//initialize the resource accessor class with the resource bundle as a parameter

GPStandardResourceAccessorresourceAccessor =

newUserDetailsResourceAccessor("com.examples.bckgco.UserDetails");

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 .

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