11.3    Custom Enterprise Java Bean Functions

As discussed in Chapter 10, when performing mappings in SAP BPM and find that the standard functions provided by SAP don’t fulfill your needs, you can create your own custom functions. This section will focus on how to create your own functions using an Enterprise Java Bean (EJB). Be aware that a basic understanding of Java is required to create an EJB function. The next section will provide step-by-step instructions for how to create a custom EJB function in SAP BPM.

Let’s start by describing the requirements for our sample custom function. The function to be created needs to provide the functionality to replace a set of characters from a sentence with another set characters, basically performing the same functionality as the replace method of the string object in Java.

To create the custom EJB function, the following tasks will need to be accomplished:

• Create a DC for the EJB.
• Create a DC for the Enterprise Application Archive (EAR).
• Create dependencies between the EJB and EAR DCs.
• Create a Java Bean (in the EJB DC) with the required mapping functionality.
• Build and deploy both the EJB and EAR DCs.
• Create a new EJB function holder in your SAP BPM DC.

Let’s now explore each of these steps.

11.3.1    Create EJB and EAR Development Components

For the sake of simplicity, we’ll create local DCs instead of using the SAP NetWeaver development infrastructure. Follow these steps:

1. Launch the SAP NetWeaver Developer Studio IDE, and select the Development Infrastructure perspective.
2. Create a new DC of the EJB module type under Java EE. Fill in the name, description, and vendor. Follow the wizard. If you’re asked to change perspective, answer No (see Figure 11.20 1 and 2).
   

   Figure 11.20    Steps in Creating an EJB Module DC

3. Repeat the previous step to create a new DC of the enterprise application type. Make sure to reference the EJB DC during the wizard, as shown in Figure 11.21. Follow the wizard until the end. If you’re asked to change perspectives, answer No.
   

   Figure 11.21    Steps in Creating an EAR Module DC

4. From the Development Infrastructure perspective, select the EJB DC that you previously created.
5. Add dependencies to the EJB DC according to the dependencies presented in Table 11.1 under the EJB DC type by clicking on the Add button from the Dependency tab (see Figure 11.22).
6. From the pop-up, filter for the appropriate dependency, and click on Finish (Figure 11.22).
7. Repeat the two previous steps for all the dependencies marked in Table 11.1 under the EJB DC type.
8. When asked to Sync Used DCs if Prompted, click on OK.

   DC Type	Dependencies
   EJB DC	engine.jee5.facade (from ENGFACADE) tc/bl/logging/api (from ENGFACADE) tc/je/sdo21/api(from ENGFACADE) tc/bpem/mapping/facade (from SERVICE-COMP)
   EAR DC	tc/je/sdo21/api (from ENGFACADE) tc/bpem/mapping/facade (from SERVICE-COMP)

   Table 11.1    List of Dependencies to be Added, Depending on the DC Type

   

   Figure 11.22    Adding Dependencies to a DC

9. Repeat steps 4 to 8 for the EAR DC.

11.3.2    Create the Enterprise Java Bean

The EJB with the function logic in Java needs to be created in the EJB DC. Follow these steps:

1. In SAP NetWeaver Developer Studio, change to the Java EE perspective.
2. Navigate to the EJB project (DC), and expand it.
3. Right-click on the ejbModule folder, select New and Session Bean (Figure 11.23 1).
4. Specify a Java package and class name 2.
5. Follow the wizard, and click on Finish.
   

   Figure 11.23    Creating a New Session Bean

6. Make your new bean implements both com.sap.glx.mapping.execution.api.invoker.SdoInvoker and com.sap.glx.mapping.execution.api.function.Function.
7. Implement the functionality of your bean in the invokeSdo method. The final source code of the class is presented in Listing 11.1.

package com.rojoconsultancy.function.custom;
import javax.ejb.Stateless;
import javax.xml.namespace.QName;
import com.sap.glx.sdo.api.SdoRenamingHelper;
import commonj.sdo.DataObject;
import commonj.sdo.Type;
import com.sap.glx.mapping.execution.api.function.*;
import com.sap.glx.mapping.execution.api.invoker.*;

/**
* Session Bean implementation class CustomReplace
*/
@Stateless
public class CustomReplace implements CustomReplaceLocal,
  Function,SdoInvoker{
    //Parameter declaration
    private static final String ORIGINALSTRING = "originalString";
    private static final String OLDCHARS = "oldChars";
    private static final String NEWCHARS = "newChars";
    private static final String RESPONSE = "response";
    private static final String NAMESPACE = "com.rojoconsultancy.
      function.custom/CustomFunction";
    private static final String 
      INPUT_ORIGINALSTRING = SdoRenamingHelper
    .renameXsdElementToSdoProperty(new QName(NAMESPACE, 
       ORIGINALSTRING), false);
    private static final String INPUT_OLDCHARS = SdoRenamingHelper
    .renameXsdElementToSdoProperty(new QName(NAMESPACE, OLDCHARS), 
       false);
    private static final String INPUT_NEWCHARS = SdoRenamingHelper
    .renameXsdElementToSdoProperty(new QName(NAMESPACE, NEWCHARS), 
      false);
    private static final String OUTPUT_RESPONSE = SdoRenamingHelper
    .renameXsdElementToSdoProperty(new QName(NAMESPACE, RESPONSE), 
      false);
/**
* Default constructor.
*/
public CustomReplace() {
// TODO Auto-generated constructor stub
}
    @Override
    public DataObject invokeSdo(DataObject dtObt, InvocationContext 
      invContext) {
        // retrieve input parameter values
        Type typeInput = dtObt.getType();
        String originalString = dtObt.getString(typeInput.getProperty(
          INPUT_ORIGINALSTRING));
        String oldChars = dtObt.getString(typeInput.getProperty(
          INPUT_OLDCHARS));
        String newChars = dtObt.getString(typeInput.getProperty(
          INPUT_NEWCHARS));
        // implement the logic of the mapping
        String responseString = originalString.replace(oldChars, 
          newChars);
        // building the output
        DataObject dataObjectResponse =
          invContext.createOutputDataObject();
        dataObjectResponse.setString(
                dataObjectResponse.getType().getProperty(
                  OUTPUT_RESPONSE), responseString);
        return dataObjectResponse;
    }
}

Listing 11.1    Source Code for the CustomReplace Java Bean

11.3.3    Build and Deploy

After implementing the logic of the EJB, it’s now time to build and deploy the source code to the SAP PO server. To build and deploy, follow these steps:

1. Open the EAR project, and right-click on the project DC.
2. Click on Build. This task will run for a few minutes.
3. Right-click on the project DC one more time
4. Click on Deploy. This task will run for a few minutes.

11.3.4    Create a New Enterprise Java Bean Function

To create a new EJB, follow these steps:

1. Log in to the Java Naming and Directory Interface (JNDI) via http://<hostname>:<port>/nwa/appcommunication.
2. From the JNDI page, filter on the name of the class (Java Bean) used to implement the custom mapping logic in the Find field. See the top red outline in Figure 11.24.
3. Copy the JNDI object name of the bean. See the lower red outline in Figure 11.24.
   

   Figure 11.24    JNDI Lookup of the EJB

4. Return to SAP NetWeaver Developer Studio, and expand the SAP BPM project.
5. Right-click on the FUNCTIONS folder, and select New EJB Function (Figure 11.25 1).
6. Give the new function a name and specify input and return parameters (Figure 11.25 2).
7. Click on Finish.
8. On the new screen, fill in the JNDI Name field (see Figure 11.26).
   

   Figure 11.25    Creating a Custom EJB Function

   

   Figure 11.26    Adding the JNDI Reference to the EJB Function

9. The newly created custom function is now present in the in the rules and functions repository and can be used (see Figure 11.27).

Figure 11.27    Using the Newly Created Custom EJB Function

The newly created CustomReplace EJB function can be used just like any normal function or rule.