9 Working with the Dynamic Java Connector

This chapter contains the following topics:

9.1 Understanding the Dynamic Java Connector

The dynamic Java connector enables a Java application to call a business function. Compared to the Java connector, the dynamic Java connector has these distinguishing features:

  • Dynamically introspects business function metadata.

    The business function metadata is introspected from the JD Edwards EnterpriseOne server during application design time by using connector APIs without pre-generating business function wrappers.

  • Dynamically calls business functions without pre-generating business function wrappers.

    Since there is no local storage of business function spec metadata, the business function used by the dynamic Java connector is always compatible with the server spec metadata.

  • Easily switches from one environment to another environment.

    The Java application can run on any environment that is compatible to the environment on which the Java application was designed.

The dynamic Java connector provides these services:

  • For application design, the dynamic Java connector permits client programs to introspect business function specification metadata.

  • For application deployment, the dynamic Java connector validates whether a client application can run through a certain JD Edwards EnterpriseOne server.

  • For application runtime, the dynamic Java connector provides an interface that permits the connector client to call the business function on the JD Edwards EnterpriseOne server.

Each server is described in detail in corresponding sections of this guide.

9.2 Designing the Dynamic Java Connector

This section provides considerations for designing the dynamic Java connector and discusses:

  • Business function spec metadata introspection.

  • Business function spec metadata validation.

  • SpecImage console.

9.2.1 Business Function Spec Metadata Introspection

To call a business function method, you need to know the business function methods that are available to be called, and you need to know about the business function metadata. This list provides examples of metadata:

  • Business function method (such as F4211BeginDoc).

  • The module name (C file name) to which a business function method belongs (such as B123456).

  • Description of the business function method (such as sales order).

  • Data structure template name that is associated with a business function method (such as D123456).

  • The attributes for all of the data items (parameters) in a business function method, such as name=szMnAddressbookNumber, itemID=1, data type=Math_Numeric, length=48, requiredType="Yes", IOType="INOUT".

In the dynamic Java connector, metadata is represented by the BSFNMethod and BSFNParameter interfaces.

9.2.1.1 BSFNMethod

The BSFNMethod interface defines APIs that enable you to retrieve metadata related to the business function method. The BSFNMethod interface defines these APIs:

  • public String getName();

  • public String getDSTemplateName();

  • public String getBSFNName();

  • public String getDescription();

  • public BSFNParameter getParameter(String paraName);

  • public BSFNParameter[] getParameters();

  • public String getFormatString();

  • public ExecutableMethod createExecutable();

  • public boolean equals(Object anotherBSFNMethod);

  • public void setEqualTo(BSFNMethod anotherBSFNMethod);

  • public String getVersion();

  • public void setVersion(String version);

9.2.1.2 BSFNParameter

The BSFNParameter interface defines APIs that enable you to retrieve metadata related to the data structure of the business function. The BSFNParameter interface defines these APIs:

  • public int getItemID();

  • public String getName();

  • public int getLength();

  • public IOType getIOType();

  • public RequiredType getRequiredType();

  • public BSFNDataType get DataType();

9.2.1.3 BSFNSpecSource

You can write a program to retrieve business function method metadata through an interface called BSFNSpecSource. The BSFNSpecSource interface defines these APIs:

  • Public BSFNMethod getBSFNMethod(String methodName) throws SpecFailureException

  • Public BSFNMethod[ ] getBSFNMethods() throws SpecFailureException

The class that implements the BSFNSpecSource interface reads the business function method metadata from an external physical repository and creates the BSFNMethod object. AbstractBSFNSpecSource is an abstract implementation of BSFNSpecSource provided by the dynamic Java connector. All customized implementations of BSFNSpecSource should be a subclass of this class. OneWorldBSFNSpecSource is the default implementation of AbstractBSFNSpecSource.

See Installing the Dynamic Java Connector.

This illustration shows the BSFNSpecSource, BSFNMethod, and BSFNParameter relationships:

Figure 9-1 Relationships among BSFNSpecSource, BSFNMethod, and BSFNParameter

Description of Figure 9-1 follows
Description of "Figure 9-1 Relationships among BSFNSpecSource, BSFNMethod, and BSFNParameter"

This code example shows how to retrieve the BSFN spec from BSFNSpecSource:

import com.jdedwards.system.connector.dynamic.spec.source.BSFNSpecSource;
import com.jdedwards.system.connector.dynamic.spec.source.OneworldBSFNSpecSource;
import com.jdedwards.system.connector.dynamic.Connector;
import com.jdedwards.system.connector.dynamic.spec.source.*;
import com.jdedwards.system.connector.dynamic.spec.SpecFailureException;
import com.jdedwards.system.connector.dynamic.ServerFailureException;

... //Declare class
        }
        public void execMethod() throws SpecFailureException,ServerFailureException
        {
                        BSFNSpecSource specSource = null;
                        int sessionID = Connector.getInstance().login("user", "pwd", "env","role");
                        //specSource = new OneWorldBSFNSpecSource(sessionID); Problem in this 
line. World should be small
                        specSource = new OneworldBSFNSpecSource(sessionID);
                        // or specSource = new ImageBSFNSpecSource("SSI.xml");
                        //Step 2: Get BSFNMethod by name from specSource
                        BSFNMethod method = specSource.getBSFNMethod("GetEffectiveAddress");
                        String methodName = method.getName();
                        System.out.println("Method name is "+methodName);
                        BSFNParameter[] paraList = method.getParameters();

                        for (int i=0; i<paraList.length;i++)
                        {
                                BSFNParameter para = paraList[i];
                                String name=para.getName();
                                System.out.println("Name is "+name);
                        }
        }

9.2.1.4 SpecDictionary

A BSFNSpecSource can contain thousands of business function methods. The dynamic Java connector provides an interface to properly categorize and organize business function methods. Without proper categorization and organization, it is difficult to navigate and find the proper business function method. To solve this problem, the dynamic Java connector provides an interface called SpecDictionary, which provides these services:

  • Categorizes business function methods in a hierarchy.

  • Masks the BSFNSpecSource and limits the number of business function methods a client can view.

The entry of SpecDictionary is called a context. A context is a set of name-to-object bindings. Every context has an associated naming convention. A context provides a lookup operation that returns the object. The dynamic Java connector provides these two concrete classes that implement the SpecDictionary:

  • OneWorldSpecDictionary, which gets the hierarchy information from the JD Edwards EnterpriseOne database.

    OneWorldSpecDictionary categorizes business function methods as DLL library - C file name - C function name.

  • ImagespecDictionary, which gets the hierarchy information from Spec Dictionary Image, which is an XML file.

Like BSFNSpecSource, third-party programs can store the spec dictionary information in their proprietary format, but they need to implement their own specDictionary to read the proprietary spec.

This diagram shows the relationship between SpecDictionary and BSFNSpecSource:

Figure 9-2 Relationship between SpecDictionary and BSFNSpecSource

Description of Figure 9-2 follows
Description of "Figure 9-2 Relationship between SpecDictionary and BSFNSpecSource"

This example code shows how to use SpecDictionary and BSFNSpecSource to browse and lookup information:

import com.jdedwards.system.connector.dynamic.spec.source.BSFNSpecSource;
import com.jdedwards.system.connector.dynamic.spec.source.OneworldBSFNSpecSource;
import com.jdedwards.system.connector.dynamic.Connector;
import com.jdedwards.system.connector.dynamic.spec.source.*;
import com.jdedwards.system.connector.dynamic.spec.SpecFailureException;
import com.jdedwards.system.connector.dynamic.ServerFailureException;
import com.jdedwards.system.connector.dynamic.spec.dictionary.Context;
//import com.jdedwards.system.connector.dynamic.spec.dictionary.
InvalidBindingException;
import com.jdedwards.system.connector.dynamic.spec.dictionary.SpecDictionary;
import com.jdedwards.system.connector.dynamic.spec.dictionary.
OneworldSpecDictionary;

... //Declare Class
        }
        public void execMethod() throws SpecFailureException,ServerFailureException
        {
                BSFNSpecSource specSource = null;
                SpecDictionary specDictionary = null;

                //Step 1: Create a SpecDictionary
                int sessionID = Connector.getInstance().login("user", "pwd", "env","role");
                specDictionary = new OneworldSpecDictionary(sessionID);
                // or specDictionary = new ImagespecDictionary("dict.xml");

                //Step 2: Bind the SpecDictionary to a SpecSource
                specDictionary.bindSpecSource(specSource);

                //Step 3a: Lookup the BSFNMethod by giving the full path
                //Problem in this line. Extra braces // BSFNMethod method =(BSFNMEthod) 
specDictionary.getSpec("CFIN.F4211.F4211BeginDoc"));
//Class name is wrong           BSFNMethod method =(BSFNMethod) specDictionary.
getSpec("CFIN.F4211.F4211BeginDoc");
                BSFNMethod method =(BSFNMethod) specDictionary.getSpec("CFIN.F4211.
F4211BeginDoc");

                //Step 3b: or navigate through the dictionary and get the context attributes
                Context initContext = specDictionary.getInitialContext();
                Context[] subContextList = initContext.getSubcontexts();
                //Illegal expression // for (int I=0;I<subContextList>.length; I++)
                for (int I=0;I<subContextList.length; I++)
                {
                        Context subContext=subContextList[I];
                        subContext.getName();
                        subContext.getDescription();
                        method=(BSFNMethod)subContext.getBoundSpec();
                }
        }

9.2.2 Business Function Spec Metadata Validation

If the dynamic Java connector program calls a business function from OneWorldBSFNSpecSource, you do not need to validate the business function metadata. The business function metadata in OneWorldBSFNSpecSource is always the same as the business function metadata that is on the JD Edwards EnterpriseOne server where the business function runs. You must ensure that all input parameters are set correctly, according to OneWorldBSFNSpecSource.

If the dynamic Java connector program calls a business function from a spec source other than OneWorldBSFNSpecSource (such as ImageBSFNSpecSource or a custom business function spec source), the business function metadata that is in the local spec source might not be compatible with the business function metadata that is on the JD Edwards EnterpriseOne server where the business function runs. Local business function spec metadata can be validated during these conditions:

Condition Explanation
Deploy Time The dynamic Java connector program validates the local spec source against the JD Edwards EnterpriseOne server spec source before run time. You should perform this validation, as all business functions in the local spec source are validated. The program can be redesigned before it is shipped.
Run Time The dynamic Java connector validates the program based on the local spec design when running business functions. During this condition, only the business function that is called is validated. Run time validations should be treated as error handling when incompatible business function specs are found.

The dynamic Java connector provides two ways to validate business function spec metadata during deploy time: SpecImageValidator APIs and SpecImageConsole command line.

The APIs for SpecImageValidator are:

  • public SpecImageValidator(BSFNSpecSource srcSpecSource).

  • public ValidationResultSet validate(SpecDictionary dictionary) throws SpecFailureException.

  • public ValidationResultSet validate(SpecDictionary dictionary, String path) throws SpecFailureException.

  • public ValidationResultSet validate(BSFNSpecSource dstSpecSource) throws SpecFailureException.

  • public ValidationResultSet validate(BSFNSpecSource dstSpecSource, String bsfnMethodName).

    Note:

    If the SpecImageConsole command line is used, the dynamic Java connector can only validate business function spec metadata from ImageBSFNSpecSource; custom business function spec sources cannot be validated.

9.2.3 SpecImageConsole

You can use the SpecImageConsole command line to generate, update, validate and synchronize spec images.

9.2.3.1 Generate Spec Image

You use the spec image console to generate or regenerate a spec image. This information is useful for generating or regenerating a spec image.

9.2.3.2 Usage

java com.jdedwards.system.connector.dynamic.util.SpecImageConsole /Generate [Other Options]

9.2.3.3 Options

/UserName <user> (required)

/Password <pwd> (required)

/Env <environment> (required)

/Role <role> (required)

/ImageStub <stub file> (required)

/ImageType <image type [SSI|SDI|ALL]> (optional, default is ALL)

/ErrorFile <error file> (optional, default is System.err)

/OutputFile <output file> (optional, default is System.out)

9.2.3.4 Explanation

Log on to JD Edwards EnterpriseOne with <user>, <pwd>, <environment>, and <role>.

Load the spec image stub from <stub file>.

Generate the spec image with the image type <image type>.

The spec image is written to the <output file> (or System.out if /OutputFile not present).

Error messages are written to the <error file> (or System.err if /ErrorFile not present).

9.2.3.5 Example

This shows example code:

java com.jdedwards.system.connector.dynamic.util.SpecImageConsole 
/Generate /ImageStub image_stub.xml /ImageType SDI /OutputFile 
image.xml /ErrorFile err.log

9.2.3.6 Update Spec Image

You use the spec image console to update or change a spec image. This information is useful for updating a spec image.

9.2.3.7 Usage

java com.jdedwards.system.connector.dynamic.util.SpecImageConsole /Update [Other Options]

9.2.3.8 Options

/UserName <user> (required)

/Password <pwd> (required)

/Env <environment> (required)

/Role <role> (required)

/SSI <SSI file> (required)

/SDI <SDI file> (optional)

/AddSpec <BSFNSpec name> (for example, F4211BeginDoc; optional)

/AddContext <full Context name> (for example, CFIN.B3100010 or CFIN.B3100010.F4211BeginDoc; optional)

/RemoveSpec <BSFNSpec name> (for example, F4211BeginDoc; optional)

/RemoveContext <full Context name> (for example, CFIN.B3100010 or CFIN.B3100010.F4211BeginDoc; optional)

9.2.3.9 Explanation

Log on to JD Edwards EnterpriseOne with <user>, <pwd>, <environment>, and <role>.

Load the <SDI file> (If option /SDI not present, then load <SSI file>) add/remove the context and BSFN spec that is specified as <full Context name> and <BSFNSpec name>.

9.2.3.10 Example

This example shows how to update the Spec Dictionary Image (sdi.xml) and the Spec Content Image (SSI.xml). The example adds Context CFIN.B00100, removes Context CFIN.B001002, adds Spec F4211BeginDoc, and removes Spec F4311BeginDoc.

java com.jdedwards.system.connector.dynamic.util.SpecImageConsole 
/Update /SDI sdi.xml /SSI ssi.xml /addContext CFIN.B001001 
/removeContext CFIN.B001002 /addSpec F4211BeginDoc /removeSpec 
F4311BeginDoc

9.2.3.11 Validate Spec Image

You use the spec image console to validate the spec image against the JD Edwards EnterpriseOne server. This information is useful for validating a spec image.

9.2.3.12 Usage

java com.jdedwards.system.connector.dynamic.util.SpecImageConsole /Validate [Other Options]

9.2.3.13 Options

/UserName <user> (required)

/Password <pwd> (required)

/Env <environment> (required)

/Role <role> (required)

/SSI <SSI file> (required)

/SDI <SDI file> (optional)

/OutputFile (optional, default to System.out)

9.2.3.14 Explanation

Log on to JD Edwards EnterpriseOne with <user>, <pwd>, <environment>, and <role>.

If option /SDI is present, validate all the BSFNSpec that bind to the <SDI file>. If /SDI is not present, validate all the BSFNSpec in the <SSI file>.

The spec image is written to the <output file> (or System.out if /OutputFile is not present).

9.2.3.15 Example

This example shows how to validate spec image using ssi.xml as the SpecDictionary and sdi.xml as the SpecSource. The example writes the validation result to validateResult.log.

java com.jdedwards.system.connector.dynamic.util.SpecImageConsole 
/Validate /SDI sdi.xml /SSI ssi.xml /OutputFile validateResult.log

9.2.3.16 Synchronize Spec Image

You use the spec image console to synchronize the spec image with the JD Edwards EnterpriseOne server. This information is useful for validating a spec image.

9.2.3.17 Usage

java com.jdedwards.system.connector.dynamic.util.SpecImageConsole /Synchronize [Other Options]

9.2.3.18 Options

/UserName <user> (required)

/Password <pwd> (required)

/Env <environment> (required)

/Role <role> (required)

/SSI <SSI file> (required)

/SDI <SDI file> (optional)

/ErrorFile <err file>(optional, default to System.err)

9.2.3.19 Explanation

Log on to JD Edwards EnterpriseOne with <user>, <pwd>, <environment>, and <role>.

If option /SDI present, synchronize all the BSFNSpec that bind to the <SDI file>. If /SDI is not present, synchronize all the BSFNSpec in the <SSI file>.

The new spec image is written to the <SSI file>. Error messages are written to <err file> (or System.err if /ErrorFile is not present).

9.2.3.20 Example

This example shows how to synchronize the spec source image, ssi.xml:

java com.jdedwards.system.connector.dynamic.util.SpecImageConsole 
/Synchronize /SSI ssi.xml 

9.3 Installing the Dynamic Java Connector

These steps illustrate how to install dynamic connector components so that you can run a dynamic Java connector application.

  1. Copy these files from the JD Edwards EnterpriseOne server to a directory on the machine that you want to use (for example, C:\JDEdwards\Interop):

    • ApplicationAPIs_JAR.jar

    • ApplicationLogic_JAR.jar

    • Base_JAR.jar

    • BizLogicContainer_JAR.jar

    • BizLogicContainerClient_JAR.jar

    • BusinessLogicServices_JAR.jar

    • castor.jar

    • commons-httpclient-3.0.jar

    • commons-logging.jar

    • Connector.jar

    • EventProcessor_JAR.jar

    • Generator.jar

    • j2ee1_3.jar

    • JdbjBase_JAR.jar

    • JdbjInterfaces_JAR.jar

    • JdeNet_JAR.jar

    • jmxremote.jar

    • jmxremote_optional.jar

    • jmxri.jar

    • log4j.jar

    • ManagementAgent_JAR.jar

    • Metadata.jar

    • MetadataInterface.jar

    • PMApi_JAR.jar

    • Spec_JAR.jar

    • System_JAR.jar

    • SystemInterfaces_JAR.jar

    • xerces.jar

    • xmlparserv2.jar

    • jdeinterop.ini

    • jdbj.ini

    • jdelog.properties

    • JDBC drivers (obtain the JDBC drivers from the database vendor)

  2. Add these files to the CLASSPATH:

    • ApplicationAPIs_JAR.jar

    • ApplicationLogic_JAR.jar

    • Base_JAR.jar

    • BizLogicContainer_JAR.jar

    • BizLogicContainerClient_JAR.jar

    • BusinessLogicServices_JAR.jar

    • castor.jar

    • commons-httpclient-3.0.jar

    • commons-logging.jar

    • Connector.jar

    • EventProcessor_JAR.jar

    • Generator.jar

    • j2ee1_3.jar

    • JdbjBase_JAR.jar

    • JdbjInterfaces_JAR.jar

    • JdeNet_JAR.jar

    • jmxremote.jar

    • jmxremote_optional.jar

    • jmxri.jar

    • log4j.jar

    • ManagementAgent_JAR.jar

    • Metadata.jar

    • MetadataInterface.jar

    • PMApi_JAR.jar

    • Spec_JAR.jar

    • System_JAR.jar

    • SystemInterfaces_JAR.jar

    • xerces.jar

    • xmlparserv2.jar

    • JDBC drivers

  3. Add the path where the jdelog.properties, jdeinterop.ini, and jdbj.ini files are located into CLASSPATH.

  4. Edit jdeinterop.ini, jdelog.properties, and jdbj.ini for proper settings.

Note:

The ptf.log file contains version information for the Java Connector. The ptf.log file is located in the Connector.jar file.

9.4 Running the Dynamic Java Connector

This section discusses:

  • Calling a business function.

  • BSFN cache.

  • Transaction using the dynamic Java connector.

  • OCM support for the dynamic Java connector.

9.4.1 Calling a Business Function

If you know the business function name and the parameters (data items) associated with the business function, you can use the dynamic Java connector to call the business function. The dynamic Java connector does not require pre-generated wrappers. This code sample shows you how to use the dynamic Java connector to call a business function:

import com.jdedwards.system.connector.dynamic.spec.SpecFailureException;
import com.jdedwards.system.connector.dynamic.ServerFailureException;
import com.jdedwards.system.connector.dynamic.Connector;
import com.jdedwards.system.connector.dynamic.spec.source.*;
import com.jdedwards.system.connector.dynamic.SystemException;
import com.jdedwards.system.connector.dynamic.ApplicationException;
import com.jdedwards.system.connector.dynamic.callmethod.*;

...//Declare Class

        public void execMethod() throws SpecFailureException,ServerFailureException
        {
                        BSFNSpecSource specSource = null;
                        // Step 1: Login
                        int sessionID = Connector.getInstance().login("user", "pwd", "env","role");

                        // Pre-condition: create the SpecDictionary or BSFNSpecSource
                        specSource = new OneworldBSFNSpecSource(sessionID);

                        // Step 2: Lookup the BSFN method from SpecDictionary or BSFNSpecSource
                        BSFNMethod bsfnMethod = (BSFNMethod)specSource.getBSFNMethod 
("GetEffectiveAddress");

                        // Step 3: create the executable method from the BSFN metadata
                        ExecutableMethod addressbook = bsfnMethod.createExecutable();
                        try
                        {

                                // Step 4: Set parameter values
                                addressbook.setValue("mnAddressNumber", "105");

                                // Step 5: Execute the business function
                                BSFNExecutionWarning warning = addressbook.execute(sessionID);

                                // Step 6: Get return parameter values
                                System.out.println("szNamealpha= " + addressbook.getValueString
("szNamealpha"));
                                System.out.println("mnAddressNumber= " + addressbook.getValueString
("mnAddressNumber"));
                                                        }
                        catch (SystemException e)
                        {
                                //SystemException is thrown when system crash, this is a fatal
                                //error and must be caught
                                System.exit(1);
                        }
                        catch (ApplicationException e)
                        {
                        // ApplicationException is thrown when business function
                        // execution fail, this is RuntimeException and thus can be
                        // unchecked. But it is strongly recommend to catch this
                        // exception
                        }
                        finally
                        {
                                //Log off and shut down connector if necessary
                                Connector.getInstance().logoff(sessionID);
                                Connector.getInstance().shutDown();
                        }
        }

The dynamic Java connector permits you to use hash tables to input parameter values. This example code illustrates how to use the Hashtable class to input parameter values:

Map input = new Hashtable();
input.put("mnAddressNumber", String.valueOf(addressNo));
addressbook.setValues(input);

The dynamic Java connector permits you to use hash tables to retrieve output values. This example code illustrates how to use the Hashtable class to retrieve output values:

Map output = addressbook.getValues();
System.out.println("szNamealpha=" + output.getValueString("szNamealpha"));

9.4.2 BSFN Cache

The dynamic Java connector fetches a business function spec from a SpecSource (JD Edwards EnterpriseOne server or an XML repository) to create an executable method. To reduce some of the overhead for creating executable methods during run business functions, the Java connector caches the executable methods after they are created.

If OneWorldSpecSource is used as SpecSource, the dynamic Java connector gets the most current business function spec from the JD Edwards EnterpriseOne server the first time the business function is called. The cache is destructed after the connector is shutdown. This cache mechanism expedites business function execution by eliminating the overhead of retrieving the business function spec for every business function call.

The duration of the cache can be configured in the jdeinterop.ini file. You can configure the setting to balance the speed of the business function execution and the update of the business function spec.

9.4.3 Transaction Using the Dynamic Java Connector

You use the dynamic Java connector to do a JD Edwards EnterpriseOne transaction in either automatic or manual mode. This example code for a purchase order entry transaction shows the steps for using the dynamic Java connector in manual mode.

int sessionID = Connector.getInstance().login("user", "pwd", "env", 
"role");
UserSession userSession = Connector.getInstance().getUserSession 
(sessionID);
boolean isManulCommit;
//set isManualCommit as true or false

//Step 1: create OneWorldTransaction
OneworldTransaction transaction = userSession.createOneworldTransaction
(isManualCommit);

// Step2: create the Purchase Order Entry executable methods (such as
// poeBeginDoc, poeEditLine, poeEndDoc) from the BSFN metadata.

//Step 3: begin the transaction
transaction.begin();

//Step 4: run BSFNs in this transaction
//set poeBeginDoc input parameters (code not provided)
BSFNExecutionWarning warning = poeBeginDoc.execute(transaction);
//set poeEditLine input parameters (code not provided)
BSFNExecutionWarning warning = poeEditLine.execute(transaction);
//set poeEndDocinput parameters (code not provided)
BSFNExecutionWarning warning = poeEndDoc.execute(transaction);

//Step 5: Commit or rollback transaction
transaction.commit();
//or transaction.rollback();

9.4.4 OCM Support for the Dynamic Java Connector

You use Object Configuration Manager (OCM) to map business functions to an enterprise server so that the dynamic Java connector can access OCM to run business functions. You no longer configure the jdeinterop.ini file to define the enterprise server from which you want to execute business functions. Using OCM support should result in an increase in performance, scalability, and load balancing. The Java interoperability server distributes the processes of the Java client to various enterprise servers depending on user, environment, and role. To take advantage of dynamic Java connector OCM support:

  • Configure the OCM and map the business function on different enterprise servers.

  • Set OCMEnabled=true in jdeinterop.ini.

  • Configure the settings in jdeinterop.ini regarding the bootstrap data source with the OCM configuration.

Ensure that OCMEnabled is set in the OCM section of the jdeinterop.ini configuration file.

9.5 Managing the User Session for the Dynamic Java Connector

This section discusses:

  • User session management for the dynamic Java connector.

  • Inbound XML request using the dynamic Java connector.

  • Logging for the dynamic Java connector.

  • Exception handling for the dynamic Java connector.

9.5.1 User Session Management for the Dynamic Java Connector

When the connector user successfully signs on, a valid user session is allocated to that user signon. The user session has status for two types of connector operations, one is for inbound business function calls, and the other is for outbound real-time events. The connector monitors the status of the user session and uses the time out settings in the jdeinterop.ini file to stop the user session when a time out setting has been reached. The connector looks at the these settings:

jdeinterop.ini File Section Setting Explanation
[CACHE] UserSession The maximum connector idle time for an inbound business function call.
[INTEROP] manual_timeout The maximum idle time for a manual transaction.
[EVENTS] outbound_timeout The maximum value of connector idle time for receiving outbound events.

The values for the settings are in milliseconds. A value of zero (0) indicates infinite time out. The settings are defined in the jdeinterop.ini section of this guide.

If an inbound user session times out, that user session cannot be used to execute a business function call. Likewise, if an outbound user session times out, that user session cannot be used for events. When both inbound and outbound sessions time out, the user session is removed from the connector. Since each user session has a corresponding handle in the JD Edwards EnterpriseOne server, you should explicitly call a connector API to log off the user session. The API log off releases the handle in the JD Edwards EnterpriseOne server when the user session is no longer used.

This sample code shows how to retrieve and manage a user session:

import com.jdedwards.system.connector.dynamic.Connector;
import com.jdedwards.system.connector.dynamic.*;
import com.jdedwards.system.connector.dynamic.ServerFailureException;

... // Declare Class
        public void execMethod() throws ServerFailureException
        {
                // Login
                int sessionID = Connector.getInstance().login("user", "pwd", "env","role");

                // Use the sessionID. If InvalidSessionException is caught, user session 
is not valid any more
                //Check the status of the usersession
                UserSession session=null;
                try
                {
                        session=Connector.getInstance().getUserSession(sessionID);
                }
                catch(InvalidSessionException ex)
                {
                        System.out.println("Invalid user session");
                }
                if(session.isInboundTimedout())
                {
                        System.out.println("User session inbound is timed out");
                }
                if(session.isOutboundTimedout())
                {
                        System.out.println("User session outbound is timed out");
                }
                //Log off and shut down connector to release user session from the server
                Connector.getInstance().logoff(sessionID);
                Connector.getInstance().shutDown();
        }

9.5.2 Inbound XML Request Using the Dynamic Java Connector

You use the dynamic Java connector to send inbound synchronous XML requests (such as XML CallObject, XML List, and XML UBE) to the JD Edwards EnterpriseOne server.

See Also

This sample code shows how to use the dynamic Java connector to execute an inbound XML request:

import com.jdedwards.system.xml.XMLRequest;

/... //Declare Class
        xmlInteropTest.EstablishSession(args);

    }

    public void EstablishSession(String[] args) throws Exception {
        String xmlDoc = new String();
                xmlDoc += "<?xml version='1.0' ?> <jdeRequest type='callmethod' user='user' ";
                xmlDoc += "       pwd='pwd' environment='env' role='role' session='' ";
                xmlDoc += "sessionidle='1800'> </jdeRequest>";

        String requestResult;

        try {
                XMLRequest xmlRequest = new XMLRequest("E1Server", 6014, xmlDoc);
                requestResult = xmlRequest.execute();
                System.out.println("Test Successful");
        } catch (Exception e) {
                System.out.println("Error in XML request");
                System.out.println(e.getMessage());
        }
    }

9.5.3 Logging for the Dynamic Java Connector

Dynamic Java connector logging is built on top of Apache Open Source Project Log4j. Log4j supports five levels of logging, as listed in order of severity, from less to more:

  • DEBUG

  • INFO

  • WARNING

  • ERROR

  • FATAL

The dynamic Java connector provides these APIs, located in ConnectorLog.java, to support logging information:

  • public static void debug(Object source).

  • public static void info(Object source).

  • public static void warn(Object source).

  • public static void warn(Object source, Throwable err).

  • public static void error(Object source, Throwable err).

  • public static void error(Object source).

  • public static void fatal(Object source).

  • public static void fatal(Object source, Throwable err).

Log properties (such as log file location, level of log messages to include in log file, and so on) are set in jdelog.properties. The jdelog.properties settings provide flexibility for dynamic Java connector applications to log messages. For example, you might set log level to ERROR or FATAL for a production environment or to DEBUG for a development or test environment.

See Also:

9.5.4 Exception Handling for the Dynamic Java Connector

The dynamic Java connector error handling design provides flexibility for you to decide how to handle application-level errors. The dynamic Java connector provides these two types of exceptions to handle errors:

  • ApplicationException

    This is the super class of all exceptions that result from application errors, such as InvalidConfigurationException (invalid INI settings), InvalidLoginException (invalid login), InvalidDataTypeException (invalid BSFN data type), and so on. The ApplicationException is a runtime exception. It is up to the client program to catch this type of exception.

  • SystemException

    This is the super class of all exceptions that result from system errors, such as ServerFailureException (server down or connection failure), BSFNLookupFailureException (unable to find BSFN information in JD Edwards EnterpriseOne tables), and SpecFailureException (unable to connect to Spec Source). It is up to the client program to catch this type of exception.

9.6 Using Sample Applications

This section discusses:

  • Sample applications.

  • Setting up sample applications.

  • Running the sample applications.

9.6.1 Sample Applications

These applications are shipped with the dynamic Java connector in their Java source form:

Application Description
Address Book Queries an AddressBook entry.
Events Subscribes to events.
Manual Commit Performs a local transaction using a Purchase Order Entry application.
Purchase Order Enters a purchase order.
Sales Order Enters a sales order.

Before you use the sample applications:

  • Create a directory for the sample applications (for example, C:\connectorsamples).

  • Install a Java Development Kit (JDK) version 1.4 or higher. Be sure to install a full JDK and not the Java Runtime Environment (JRE).

    See Installing the Dynamic Java Connector.

  • Set the JAVA_HOME environment variable to the JDK parent directory.

  • Configure the jdeinterop.ini, jdelog.properties, and jdbj.ini files and place the files in the directory you created for the sample applications (for example, C:\connectorsamples).

    Note:

    You can download the JDK from this Oracle website (http://www.oracle.com/technetwork/java/javase/overview/index.html).

9.6.2 Setting Up Sample Applications

The sample applications are shipped in their Java source form, which provides the usage of the dynamic Java connector API. You must set up these sample applications in the environment before you can run them. Use these steps to set up the sample applications:

  1. Locate the connector_samples_src.jar and connectorsamples.zip files.

    These files are on the JD Edwards EnterpriseOne Java Server CD, under the system/classes/samples directory.

  2. Unzip the entire contents of the connector_samples_src.jar file and connectorsamples.zip into the directory you created (for example, C:\connectorsamples).

    The .jar file is a traditional .zip file with the Java .jar extension. The .jar file contains all of the sample application source files (.java files). All of the .jar files that you need for both setting up and running the sample applications are in the system/classes directory on the JD Edwards EnterpriseOne Java Server CD.

  3. Open each bat file in the samples directory and change the value of JAVA_HOME to the path where JDK is installed on the system.

  4. Configure the jdeinterop.ini, jdelog.ini, and jdbj.ini files and place them in the samples directory.

    You can use .tmpl files as a guide for doing this.

9.6.3 Running the Sample Applications

To run each application, run the .bat file for that application.

Sample Application Bat File name
Address Book runDynConAddressBook.bat
Events runDynConNewEventDriver.bat
Manual Commit runDynConPOEManualCommit.bat
Purchase Order runDynConPOE.bat
Sales Order runDynConSOE.bat

Note:

If you are running on a non-windows platform, you can open the bat file that corresponds to the sample application that you want to use in a text editor and copy the JAVA command in the bat file. This command can then be run from the console of your platform. The correct version of JAVA must be in the system path for you to run the application.