7 EnterpriseOne ADF Container

EnterpriseOne ADF applications are composed of ADF bounded task flows packaged into ADF Library JAR files. These JAR files are not deployed as web applications and cannot run individually on an ADF Server. Instead, the packaged ADF applications are deployed in an ADF Library and run inside the EnterpriseOne ADF Container (JDEADFContainer), which is a web application that runs bounded task flows in dedicated, dynamic regions. Within the JDEADFContainer, multiple ADF applications launched from an EnterpriseOne menu run simultaneously with only one ADF application visible to the user at any one time.

To launch an ADF application from EnterpriseOne, a Solution Explorer task of type "ADF Application" must first exist that specifies both an EnterpriseOne proxy application name and an ADF task flow id. Optionally, the proxy application version can also be specified on the task. Otherwise, ZJDE0001 is used as the default version. When the Solution Explorer task is launched, the proxy app name, version, jargon code, and ADF task flow id from the task are sent to the JDEADFContainer. If the ADF task flow is found, the ADF application launches inside an available region of the JDEADFContainer web application.

This chapter contains the following topics:

Section 7.1, "EnterpriseOne Proxy Applications"
Section 7.2, "E1ADFUtils Overview"

7.1 EnterpriseOne Proxy Applications

Each EnterpriseOne ADF application should have an accompanying EnterpriseOne "proxy" application for security, version control, and processing options. Oracle's standard is to name both the EnterpriseOne proxy and ADF applications beginning with the letter E, like E01012.

7.1.1 Understanding Processing Options in Proxy Applications

The EnterpriseOne proxy application must have a processing option field to specify a version for every EnterpriseOne application called by the ADF application that has versions. The versions specified in the processing options can then be used when the ADF application executes form service requests in the data control methods.

7.1.2 Retrieving Proxy Application's Processing Options

You use the AIS PO Service to retrieve processing options for EnterpriseOne proxy applications and applications called by the ADF application. The JDEADFContainer will pass the proxy application's name and version to the ADF application as input parameters, which are stored as Page Flow Scope variables. The below example first retrieves processing options for the proxy application and then retrieves processing options for Address Book based on the P01012 version specified for the proxy application.

Example 7-1 Calling AIS Processing Option Service

if (AISClientCapability.isCapabilityAvailable(loginEnv, AISClientCapability.PROCESSING_OPTION))
{
   try
    {
        String appName = (String) ADFContext.getCurrent().getPageFlowScope().get("appName");
        if ((appName == null) || (appName.length() == 0))
        {
            appName = "E01012";
        }
        
        String appVersion = (String) ADFContext.getCurrent().getPageFlowScope().get("appVersion");
        if ((appVersion == null) || (appVersion.length() == 0))
        {
            appVersion = "ZJDE0001";
        }
 
        ProcessingOptionRequest e01012PORequest = new ProcessingOptionRequest(loginEnv);
        e01012PORequest.setApplicationName(appName);
        e01012PORequest.setVersion(appVersion);
 
        String response = JDERestServiceProvider.jdeRestServiceCall(loginEnv, e01012PORequest, 
                                                                     JDERestServiceProvider.POST_METHOD, 
                                                                     JDERestServiceProvider.PO_SERVICE);
        ProcessingOptionsSet e01012POSet = loginEnv.getObjectMapper().readValue(response, ProcessingOptionsSet.class);
 
        if (e01012POSet != null)
        {
            p01012Version = (String) e01012POSet.getOptionValue("szP01012Version_2");
            if ((p01012Version == null) || (p01012Version != null && p01012Version.length() == 0))
            {
                p01012Version = "ZJDE0001";
            }
            
            ProcessingOptionRequest p01012PORequest = new ProcessingOptionRequest(loginEnv);
            p01012PORequest.setApplicationName("P01012");
            p01012PORequest.setVersion(p01012Version);
            
            String response1 = JDERestServiceProvider.jdeRestServiceCall(loginEnv, p01012PORequest, 
                                                                          JDERestServiceProvider.POST_METHOD, 
                                                                          JDERestServiceProvider.PO_SERVICE);
            ProcessingOptionsSet p01012POSet = loginEnv.getObjectMapper().readValue(response1, ProcessingOptionsSet.class);
            
            if (p01012POSet != null)
            {
                hideTax = (String) p01012POSet.getOptionValue("HideTax_4");
                displaySupplierMaster = (String) p01012POSet.getOptionValue("GoToSupplierMaster_5");
                displayCustomerMaster = (String) p01012POSet.getOptionValue("GoToCustomerMaster_6");
                searchTypeDefault = (String) p01012POSet.getOptionValue("SearchTypeDefault_7");
                displayCSMS = (String) p01012POSet.getOptionValue("GoToCSMS_8");
                p0100041Version = (String) p01012POSet.getOptionValue("Version_9");
                selfServiceMode = (String) p01012POSet.getOptionValue("cSelfServiceMode_10");
                typeCode = (String) p01012POSet.getOptionValue("cTypeCode_11");
                postalCodeValidate = (String) p01012POSet.getOptionValue("cPostalCodeValidate_12");
                postalAddressRetrieval = (String) p01012POSet.getOptionValue("cPostalAddressRetrieval_13");
                p03013Version = (String) p01012POSet.getOptionValue("szCustMasterVersion_VER_14");
                p04012Version = (String) p01012POSet.getOptionValue("szSuppMasterVersion_VER_15");
            }
        }
    }
    catch (CapabilityException e)
    {
        processErrorException(e);
    }
    catch (JDERestServiceException e)
    {
        processErrorException(JDERestServiceProvider.handleServiceException(e));
    }
    catch (Exception e)
    {
        processErrorException(e);
    }
}
else
{
   // Processing Option cability is not supported on AIS.  Use default search type.
    searchTypeDefault = "E";
}

As shown in the above example, you retrieve a processing option value from the ProcessingOptionSet object using an identifier. This identifier can be found in the data structure generated for the Processing Option Template in the Object Management Workbench. You use this data structure to find the identifier for each processing option value you need for your ADF application.

Example 7-2 Generated Data Structure for Processing Option Template

/**
 * TYPEDEF for Data Structure
 * T01012 : Address Book - New Processing Option
 *
 * Copyright Oracle USA
 *
 * This is a JDEdwards EnterpriseOne generated file.
 * Do not modify this file.
 * Only re-generate with the appropriate tool.
 * Generation Date : 7/9/2015
 */
 
#ifndef DATASTRUCTURE_T01012
#define DATASTRUCTURE_T01012
 
typedef struct tagDST01012
{
  JCHAR          HideTax;
  JCHAR          GoToSupplierMaster;
  JCHAR          GoToCustomerMaster;
  JCHAR          SearchTypeDefault[4];
  JCHAR          GoToCSMS;
  JCHAR          Version[11];
  JCHAR          cSelfServiceMode;
  JCHAR          cTypeCode;
  JCHAR          cPostalCodeValidate;
  JCHAR          cPostalAddressRetrieval;
  JCHAR          szCustMasterVersion_VER[11];
  JCHAR          szSuppMasterVersion_VER[11];
} DST01012 , *LPDST01012;
 
#define IDERRHideTax_4                            4L
#define IDERRGoToSupplierMaster_5                 5L
#define IDERRGoToCustomerMaster_6                 6L
#define IDERRSearchTypeDefault_7                  7L
#define IDERRGoToCSMS_8                           8L
#define IDERRVersion_9                            9L
#define IDERRcSelfServiceMode_10                  10L
#define IDERRcTypeCode_11                         11L
#define IDERRcPostalCodeValidate_12               12L
#define IDERRcPostalAddressRetrieval_13           13L
#define IDERRszCustMasterVersion_VER_14           14L
#define IDERRszSuppMasterVersion_VER_15           15L
 
#endif /* DATASTRUCTURE_T01012 */

7.2 E1ADFUtils Overview

E1ADFUtils is a helper class included in the E1UserSession.jar that provides several static methods for accessing functionality available through the JDEADFContainer, including launching an EnterpriseOne menu task, launching an EnterpriseOne application, and displaying error and warning messages using the JDEADFContainer's message popup dialog.

Note:

These features are only available when the EnterpriseOne ADF application launches from an EnterpriseOne Solution Explorer task and executes in the JDEADFContainer web application. If the EnterpriseOne ADF application is run on JDeveloper's Integrated WLS, the application code to utilize these features will execute without error, but the JDEADFContainer is not available to provide the desired functionality.

Return Type	Method	Description
void	launchE1Task(String taskId)	Launches the EnterpriseOne object associated with the specified task id.
void	launchE1Application(E1FormInterconnect formInterconnect)	Launches the specified EnterpriseOne application.
void	addErrorMessages(List<E1Message> messages)	Adds a list of E1Message objects to the JDEADFContainer's error message list.
void	addErrorMessage(String message)	Adds a single message to the JDEADFContainer's error message list.
void	addWarningMessages(List<E1Message> messages)	Adds a list of E1Message objects to the JDEADFContainer's warning message list.
void	addWarningMessage(String message)	Adds a single message to the JDEADFContainer's warning message list.
void	addInformationMessages(List<E1Message> messages)	Adds a list of E1Message objects to the JDEADFContainer's information message list.
void	addInformationMessage(String message)	Adds a single message to the JDEADFContainer's information message list.
void	launchMessagePopup()	Displays the JDEADFContainer's message popup dialog. Once the dialog is displayed, the message lists are cleared.
void	initializeAppInstance(String path)	Retrieves values from the About.properties file for the ADF application to display in the About dialog.

7.2.1 Launching EnterpriseOne Menu Task

To launch an EnterpriseOne menu task from your ADF application, you only need to specify the task id when calling the launchE1Task() method.

Example 7-3 Launching EnterpriseOne Menu Task

// Launch Address Book menu task.E1AdfUtils.launchE1Task("11/G1341");

7.2.2 Launching an EnterpriseOne Application

To launch an EnterpriseOne application from your ADF application, you need to first create an E1FormInterconnect object to identify the application and form to run and the form interconnect values to pass to the EnterpriseOne application form. Then you call the launchE1Application() method, passing the E1FormInterconnect object as the sole parameter.

Example 7-4 Launching and EnterpriseOne Application

// Launch Address Book Work With Addresses form.
E1FormInterconnect form = new E1FormInterconnect();
form.setApplication("P01012");
form.setForm("W01012B");
form.setVersion("ZJDE0001");
form.addFormInterconnectValue("1", "7500");
form.addFormInterconnectValue("2", "E");
E1AdfUtils.launchE1Application(form);

7.2.3 Displaying Error and Warning Messages

When a form service request executes on the JAS server, any errors and warnings displayed on the EnterpriseOne form are returned to the ADF application in the JSON response. You can retrieve these messages from the response object and display them to the user using the JDEADFContainer's message popup, which provides a modal dialog window for error, warning, and information messages. You will typically perform the following steps to display messages to the user:

To display a single message, call the E1AdfUtils method to add the individual message to one of the JDEADFContainer's exception lists.
To display multiple messages, collect error, warning, and information messages in separate lists and call the E1AdfUtils methods to add these lists to the JDEADFContainer's exception lists.
Call the launchMessagePopup() method to display the JDEADFContainer's message popup.

Example 7-5 Display a Single Error Message

if (AISClientCapability.isCapabilityAvailable(loginEnv, AISClientCapability.GRID))
{
    // Code to perform Form Service Request and process response.
}
else
{
    E1AdfUtils.addErrorMessage("The grid capability is not supported on AIS Server.");
    E1AdfUtils.launchMessagePopup();
}

Example 7-6 Display Multiple Error Messages

FormRequest formRequest = new FormRequest(loginEnv);
 
// Populate form request.
...condensed...
 
// Execute form request to add new employee to Employee Master using P060116Q.
String response = JDERestServiceProvider.jdeRestServiceCall(loginEnv, formRequest,
                                                             JDERestServiceProvider.POST_METHOD, 
                                                             JDERestServiceProvider.FORM_SERVICE_URI);
 
P060116Q_W060116QA_FormParent p060116FormParent = loginEnv.getObjectMapper().readValue(response, P060116Q_W060116QA_FormParent.class);
                
if (p060116FormParent != null)
{
    // If insert was successful, clear input fields.  Otherwise, display errors.
    FormErrorWarning[] errors = p060116FormParent.getFs_P060116Q_W060116QA().getErrors();
    List<E1Message> errorList = new ArrayList<E1Message>();
    if (errors.length > 0)
    {
        for (int i = 0; i < errors.length; i++)
        {
            errorList.add(new E1Message(E1Message.Severity.ERROR, errors[i].getMOBILE()));
        }
        
        E1AdfUtils.addErrorMessages(errorList);                 
        E1AdfUtils.launchMessagePopup();
    }
    else
    {
        clearInputFields();
    }
}

As mentioned previously, the JDEADFContainer's message popup will only display when the ADF application is running inside the container. In order to display messages when the application is running on JDeveloper's Integrated WLS, you can conditionalize your error reporting code to use the Java Server Faces messaging feature, as shown in the below example:

Example 7-7 Display Error Messages When Running Locally on JDeveloper's Integrated WLS

if (AISClientCapability.isCapabilityAvailable(loginEnv, AISClientCapability.GRID))
{
    // Code to perform Form Service Request and process response.
}
else
{
    String msg = "The grid capability is not supported on AIS Server";
    if (runningInJDEADFContainer)
    {
        E1AdfUtils.addErrorMessage(msg);
        E1AdfUtils.launchMessagePopup();
    }
    else
    {
        FacesContext.getCurrentInstance().addMessage("E1ADFApp", new FacesMessage(FacesMessage.SEVERITY_ERROR, "AIS Capability Not Supported ", msg));
    }
}

See Section 4.1, "Creating a Connection to AIS Server" to review the code that first determines whether the ADF application is running locally or in the JDEADFContainer and then sets the runningInJDEADFContainer boolean accordingly.

7.2.4 Supporting About Information

The EnterpriseOne container provides an About button that enables you to display information about the ADF application launched within the container. When you click the About button, a dialog box, like the example below, appears and displays similar information: This image is described in surrounding text.

The dialog box has two sets of information: Application Information, and Task Information. The Application Information is provided by the individual ADF Bounded Task flow.

To setup About Information

Create a new file in your project named about.properties and include the following content:

[About]

applicationName=JD Edwards EnterpriseOne Address Book Reference Application

version=1.0.0

appID=E01012

Make sure to place the file in a package that is named uniquely. The standard location would be with the application named package. In this example it is in the com.oracle.e1.E01012 package.
During the initialization of your application you must communicate to the container where the about.properties for your application is stored. Make sure you have a handshakeId before calling the E1AdfUtils.initializeAppInstance() method. Having a handshakeId is an indication that your application is running within the container.
Pass the package path to your about.properties file as in this example:

Note:
The example application shown above is named E01012. "E" is the naming convention Oracle recommends you use for your ADF applications.

E1AdfUtils.intializeAppInstance("/com/oracle/e1/E01012/");