Show TOC

Implementing a Background Callable ObjectLocate this document in the navigation structure

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.

Tip

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:

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

    Note

    The technical names that you use for the parameters of the callable object may only contain numbers, letters from the Latin alphabet, and underscore.

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);
        
         } ...
 
   }
Example
  1. Set the result states for the callable object.

    In the example below, a result state is defined that indicates successful execution.

Example 
publicIGPTechnicalDescription getDescription(Locale originalLocale) {
 
      try {
         ...
         //add a result state for successful execution
        IGPCOResultStateInfosuccess =
         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.

  1. 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() .
Example 
publicvoid execute(IGPExecutionContext executionContext)
      throwsGPTechnicalCallableObjectException{
      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();
      } 
   }
  1. Set a result state that is reached when the object is successfully executed.
Example 
publicvoid execute(IGPExecutionContext executionContext)
      throwsGPTechnicalCallableObjectException{
      try {
         ...
        try{
            ...
           //set result state
            executionContext.setResultState("Success");
            ...
        }...
      }
   }
  1. Finally, complete the object execution by calling method processingComplete() of the execution context.
Example 
publicvoid execute(IGPExecutionContext executionContext)
      throwsGPTechnicalCallableObjectException{
      try {
         ...                 
        
        //complete object execution
        executionContext.processingComplete();
                   
     }
   }

Implement Process Exception Handling

  1. Add a process exception for the background callable object. You do this in the getDescription() method.
Example 
publicIGPTechnicalDescription getDescription(Locale originalLocale) {
 
      try {
         ...
         //add a process exception for the callable object
     
technicalDescription.addProcessException("EXCEPTION_NO_USER_FOUND");
        returntechnicalDescription;
      }  ...
 
   }
  1. Implement a catch clause in the execute() method, so that in the case of an UME exception, a process exception occurs.
Example 
publicvoid execute(IGPExecutionContext executionContext)
     throwsGPTechnicalCallableObjectException{
     String userId = null;
     try {
     ...
         try{
         ...
        } catch (UMException e) {
     executionContext.setProcessException("EXCEPTION_NO_USER_FOUND");
           }
     executionContext.processingComplete();
    } ...
}

Implement Technical Exception Handling

  1. 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 .
  2. 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 .
    Tip

    This exception is thrown if the technical names contain forbidden characters. Therefore, it should not occur unless the rules for the names are violated.

Example 
publicIGPTechnicalDescription 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;
   }
}
  1. 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.
Example 
   public void execute(IGPExecutionContext executionContext)
      throwsGPTechnicalCallableObjectException{
      String userId = null;        
      try {
        
      ...
        
      } catch (GPInvocationException e) {
         throw newGPTechnicalCallableObjectException(logger,resourceAccessor, "ERROR_PARAMETERS", e);
      } catch (GPEngineException e) {
         throw newGPTechnicalCallableObjectException(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:

  1. In the same package, create a new class that extends com.sap.caf.eu.gp.co.api.GPStandardResourceAccessor - for example, UserDetailsResourceAccessor.
  2. In your resource accessor class, add the constructor from the super class, as shown in the example below.
Example 
publicclass UserDetailsResourceAccessor extendsGPStandardResourceAccessor{
 
   /**
    * @param bundleName
    */
   public UserDetailsResourceAccessor(String bundleName) {
      super(bundleName);
   }
}
  1. 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.
Example 
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
  1. 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.
Example 
publicclass 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