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.
For more information about the interfaces used for the implementation, see the API documentation at http://www.sdn.sap.com/irj/sdn/javadocs.
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
...
1. In Project Explorer view, expand the tree of your Java DC project, and select src. Choose File → New → Package.
2. Enter a name for your package, such as com.examples.bckgco. Choose Finish.
3. 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.
4. 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:
5. 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).
The technical names that you use for the parameters of the callable object may only contain numbers, letters from the Latin alphabet, and underscore.
public IGPTechnicalDescription 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 IGPAttributeInfo userId = 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);
} ...
} |
6. Set the result states for the callable object.
In the example below, a result state is defined that indicates successful execution.
public IGPTechnicalDescription getDescription(Locale originalLocale) {
try { ... //add a result state for successful execution IGPCOResultStateInfo success = technicalDescription.addResultState("Success");
//add result state description success.setDescriptionKey("Success_desc"); return technicalDescription; } ...
} |
Edit Method execute()
In this method you implement the runtime behavior of the callable object.
7. 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().
public void execute(IGPExecutionContext executionContext) throws GPTechnicalCallableObjectException { try {
//retrieve the runtime representation of the input structure IGPStructure input = executionContext.getInputStructure(); //retrieve the value of the input parameter String userId = (String) input.getAttributeAsString("UserID");
//retrieve the runtime representation of the output structure IGPStructure output = executionContext.getOutputStructure(); IGPStructure user = output.addStructure("User");
try { //find user in user management IUser umeUser = UMFactory.getUserFactory().getUserByLogonID(userId);
//set values to output parameters user.setAttributeValue("firstName", umeUser.getFirstName()); user.setAttributeValue("lastName", umeUser.getLastName()); user.setAttributeValue("phone", umeUser.getTelephone()); user.setAttributeValue("fax", umeUser.getFax());
//set result state executionContext.setResultState("Success");
}... //complete object execution executionContext.processingComplete(); } } |
8. Set a result state that is reached when the object is successfully executed.
public void execute(IGPExecutionContext executionContext) throws GPTechnicalCallableObjectException { try { ... try { ... //set result state executionContext.setResultState("Success"); ... }... } } |
9. Finally, complete the object execution by calling method processingComplete() of the execution context.
public void execute(IGPExecutionContext executionContext) throws GPTechnicalCallableObjectException { try { ...
//complete object execution executionContext.processingComplete();
} } |
Implement Process Exception Handling
10. Add a process exception for the background callable object. You do this in the getDescription() method.
public IGPTechnicalDescription getDescription(Locale originalLocale) {
try { ... //add a process exception for the callable object technicalDescription.addProcessException("EXCEPTION_NO_USER_FOUND"); return technicalDescription; } ...
} |
11. Implement a catch clause in the execute() method, so that in the case of an UME exception, a process exception occurs.
public void execute(IGPExecutionContext executionContext) throws GPTechnicalCallableObjectException { String userId = null; try { ... try{ ... } catch (UMException e) { executionContext.setProcessException("EXCEPTION_NO_USER_FOUND"); } executionContext.processingComplete(); } ... } |
Implement Technical Exception Handling
12. 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.
13. 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.
This exception is thrown if the technical names contain forbidden characters. Therefore, it should not occur unless the rules for the names are violated.
public IGPTechnicalDescription getDescription(Locale originalLocale) {
try { ... } catch (GPInvocationException e) { logger.logT( Severity.ERROR, Category.APPLICATIONS, "Incorrect technical name"); logger.traceThrowableT( Severity.ERROR, "Exception while creating technical description: ", e); return null; } } |
14. 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.
public void execute(IGPExecutionContext executionContext) throws GPTechnicalCallableObjectException { String userId = null; try {
...
} catch (GPInvocationException e) { throw new GPTechnicalCallableObjectException (logger, resourceAccessor, "ERROR_PARAMETERS", e); } catch (GPEngineException e) { throw new GPTechnicalCallableObjectException (logger, resourceAccessor, "INTERNAL_ERROR", e); } } } |
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:
15. In the same package, create a new class that extends com.sap.caf.eu.gp.co.api.GPStandardResourceAccessor – for example, UserDetailsResourceAccessor.
16. In your resource accessor class, add the constructor from the super class, as shown in the example below.
public class UserDetailsResourceAccessor extends GPStandardResourceAccessor {
/** * @param bundleName */ public UserDetailsResourceAccessor(String bundleName) { super(bundleName); } } |
17. 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.
CO_NAME=User Details CO_DESCRIPTION=User Details Background Callable Object UserID=User ID User=User firstName=First Name lastName=Last Name fax=Fax phone=Telephone Success=Successful execution Success_desc=The execution completed successfully ERROR_PARAMETERS=Error while setting/getting parameters INTERNAL_ERROR=Internal error USER_NOT_FOUND=User with ID {0} not found |
18. 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.
public class UserDetailsCallableObject implements IGPBackgroundCallableObject {
GPStandardResourceAccessor resourceAccessor = new UserDetailsResourceAccessor("com.examples.bckgco.UserDetails");
... } |
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.
Creating and Deploying a Java Enterprise Application