Implementing a Background Callable Object
Use
The Java class that you want to use as a callable object for background execution must implement the interface com.sap.caf.eu.gp.co.api.IBackgroundCallableObject . It enables the execution of the class within the Guided Procedures (GP) framework.
The most important aspects of the implementation include:
- Defining input, output parameters, and result states in method getDescription()
- Setting the output parameters and completing the execution in method execute()
- Implementing localization for texts
- Implementing exception handling
Prerequisites
To be able to create the required imports in the Java class source code, you must have configured your Java development component.
More information: Creating a Java Development Component .
Procedure
Create the Java Class
- In Project Explorer view, expand the tree of your Java DC project, and select src . Choose File → New → Package.
- Enter a name for your package, such as com.examples.bckgco . Choose Finish.
- In your project tree, select the package you created, and choose File → New → Class.
- Enter a name for the class, such as UserDetailsCallableObject .
- To define that the class implements IGPBackgroundCallableObject , choose Add… next to Interfaces and search for the interface.
- Make sure only the option Inherited abstract methods is selected.
- Choose Finish. The class opens in the Java editor.
Edit Method getDescription()
This method returns the technical description of the callable object, which contains metadata about the object's input, output, and configuration parameters, as well as its result states.
To define the callable object:
- Retrieve the preexisting root structures for the input and output parameters using an instance of the com.sap.caf.eu.gp.co.api.IGPTechnicalDescription interface. You can define sub-structures and attributes to structures using the interfaces IGPStructureInfo and IGPAttributeInfo .
In this example, you define a single input parameter for the user ID in the root structure. For the output parameters, you create a structure where you define the attributes for the user details that you retrieve - first and last name, telephone and fax numbers (see the coding example below).
publicIGPTechnicalDescription getDescription(Locale originalLocale) {
try {
//create technical description instance IGPTechnicalDescription technicalDescription = GPCallableObjectFactory.newTechnicalDescription( "CO_NAME", "CO_DESCRIPTION", resourceAccessor, originalLocale); //get root structure for input parameters IGPStructureInfo input = technicalDescription.getInputStructureInfo(); //define attributes for input parameters IGPAttributeInfouserId = input.addAttribute("UserID", IGPAttributeInfo.BASE_STRING);
userId.setMultiplicity(IGPAttributeInfo.MULITIPLICITY_1_1); //get root structure for output parameters IGPStructureInfo output = technicalDescription.getOutputStructureInfo(); //add a sub-structure for the output IGPStructureInfo user = output.addStructure("User");
//define attributes in output sub-structure user.addAttribute("firstName", IGPAttributeInfo.BASE_STRING);
user.addAttribute("lastName", IGPAttributeInfo.BASE_STRING);
user.addAttribute("phone", IGPAttributeInfo.BASE_STRING);
user.addAttribute("fax", IGPAttributeInfo.BASE_STRING);
} ... } |
- Set the result states for the callable object.
In the example below, a result state is defined that indicates successful execution.
Edit Method execute()
In this method you implement the runtime behavior of the callable object.
- You use an instance of com.sap.caf.eu.gp.co.api.IGPExecutionContext to retrieve runtime information - for example, to add values to the attributes you have defined in method getDescription() .
- Set a result state that is reached when the object is successfully executed.
- Finally, complete the object execution by calling method processingComplete() of the execution context.
Implement Process Exception Handling
- Add a process exception for the background callable object. You do this in the getDescription() method.
- Implement a catch clause in the execute() method, so that in the case of an UME exception, a process exception occurs.
Implement Technical Exception Handling
- Create an instance of com.sap.tc.logging.Location that you will use to log error messages. For more information, see the API documentation at http://www.sdn.sap.com/irj/sdn/javadocs .
- In method getDescription() implement the catch clause of the try-catch block to trace and log an invocation exception. In case of an error, the method should return null .
- In method execute() , implement the catch clause so that a GP technical exception is thrown in case of any error that occurs. You can localize the detailed messages for each individual error.
Implement Localization
The names that you have defined for the callable object parameters can be automatically used as keys for localized messages that are displayed at runtime. You can also set additional keys, as shown in the example for defining a result state description above.
To implement localization:
- In the same package, create a new class that extends com.sap.caf.eu.gp.co.api.GPStandardResourceAccessor - for example, UserDetailsResourceAccessor.
- In your resource accessor class, add the constructor from the super class, as shown in the example below.
- In the same package, create a text file with extension.properties - for example, UserDetails.properties. Enter all texts that you want to localize as key-value pairs in the format shown in the example below.
- In class UserDetailsCallableObject instantiate the resource accessor class that you created. Enter the name of the resource bundle as a fully qualified name including the package, as in the example below.
Result
Save the files, and build your project. You have implemented a Java class that can be exposed as a callable object in GP.
Now you must create a Java Enterprise Application and deploy it to AS Java.
More Information:
UserDetailsCallableObject - the complete source code of sample class.