Using your JAR file: The basics

Once you’ve created and deployed your JAR file, it is ready for use in a JSP or Java application. The machine used by the Java developer must be properly configured. See Setting up your environment for development.

If you are using Java connection pooling, follow the steps in Using your JAR file with connection pooling instead of the steps in this topic.

Associate the component with your project

Before using the JAR file, you’ll need to associate it with your project in your development environment. The method for doing this depends on the environment. If you are using Workbench, first make sure your project is the active project. Then, select Project > Project Properties. On the Files tab, click the Add Files button, navigate to the JAR file, and add it.

You can view the methods in the JAR file using the object/class browser supplied with your development environment. In Workbench, go to the Symbols tab in the project toolbar and expand the Packages/Namespaces node under the Workspace node. You’ll see a node for your JAR file. Expand it to see the classes in your JAR file. Expand the classes to view your own methods, along with the xfNetLink Java utility methods. The utility methods enable you to establish a connection with xfServerPlus, disconnect from xfServerPlus, and perform other utility functions, such as setting properties and running a debug session. See the Method reference for a complete list of utility methods.

Import the necessary packages

The import statement enables you to more easily access the classes in the imported package.

For Java applications, include an import statement for your package so that you can easily access the classes in your JAR file. For JSP applications, you do not need to import your package.

For example, in a Java application:

import com.ABCComputers.ConsultPro.*;

Instantiate an instance of a procedural class

There are two constructors included in procedural classes: the default constructor and the “ini file” constructor.

The default constructor takes no parameters. Use it in the following circumstances:

You are using an xfNetLink Java properties file named xfNetLnk.ini that resides in the directory that your Java application starts in or in the default location required by your web server and servlet container.
You are using the “set” methods to specify the host, port number, logging, and encryption options. If one of these properties is not set with a set method, and there is a properties file named xfNetLnk.ini present that includes the setting, the setting in the xfNetLnk.ini file will be used.

For example, to use the default constructor in a Java application:

AppLogin appLog = new AppLogin();

Or, in a JSP page:

<jsp:useBean id="appLog" scope="session" class="ConsultIt.AppLogin">

The “ini file” constructor enables you to pass a Java String naming a specific properties file. Use it when your properties file is not named xfNetLnk.ini.

For example, to use the ini file constructor:

AppLogin appLog = new AppLogin("myPropFile.ini");

Set properties for the client

If you are not using a properties file, use the set methods in the class to set the properties for xfServerPlus host name and port and logging options. If you are using a properties file, you can override individual settings in it by using the set methods. See the Method reference for a complete list of the set methods.

You must specify the host name and port either with the set methods or in a properties file. The other properties are optional.

For example:

appLog.setxfHost("elmo");
appLog.setxfPort(2356);
appLog.setxfLogging(true);
appLog.setxfLogfile("c:\\temp\\consult.log");

Connect to xfServerPlus

When you make a connection to xfServerPlus, the xfServerPlus process creates a dbs (or dbr if XFPL_DBR is set). Once created, this dbs continues to run and process requests from the client until the connection is closed, and then the dbs is closed by the xfServerPlus process.

There are several ways to establish the connection with xfServerPlus.

Use connect(). This is the recommended method. It enables you to make several calls using the same connection, and then disconnect. There are several advantages to using connect(): it offers improved performance; you can maintain state between calls; and you can share this type of connection with other objects (see next bullet).

When you use connect(), you are instantiating an SWPConnect object, which then becomes a property of your object. The SWPConnect object is the actual connection to your xfServerPlus machine.

For example:

appLog.connect();

Share a connection. Two or more objects can share a connection. This method improves performance because several objects are sharing the same xfServerPlus session rather than each object making its own connection. To share a connection, you must first establish it with connect(), and then use the getConnect() and shareConnect() methods. These objects then share a reference to the SWPConnect object.

In the example below, we instantiate two new procedural classes and use the connect() method to establish a connection for one of them. We then instantiate the xyz object to hold the connection, and use the getConnect() method to get it. Finally, we call the shareConnect() method of the consult object and pass the xyz object. You can pass the same xyz object multiple times to share the connection among several objects.

AppLogin appLog = new AppLogin();
Consultant consult = new Consultant();
appLog.connect();
java.lang.Object xyz = null;
xyz = appLog.getConnect();
consult.shareConnect(xyz);

Create the connection automatically. This is referred to as an implied connection. When you make a call using one of the Synergy methods in your JAR file, the connection is created automatically and then disconnected when the call is complete. This is the easiest method to use because it makes access to xfServerPlus completely transparent. However, this method does not allow you to maintain state between calls and requires more overhead because a connection is opened and closed for each call. If you use this method and experience performance problems, you may want to use an explicit connect() instead.

In the example below, the consult object is instantiated, and then the postCharge() method is called, without first calling the connect() method.

Consultant consult = new Consultant();
consult.postCharge(charge, return_msg);

Invoke methods in the component

Make calls to your Synergy methods and pass the parameters. If you generated Javadoc for your JAR file, it will include the information necessary to use the methods, such as the parameter data types.

Parameters that were not flagged as required in the SMC were converted to required parameters when you generated the Java class wrappers because you must always pass all parameters in Java.

For example, to invoke the login() method in the AppLogin class:

String id = new String("MFranklin");
String password = new String("123abc");
appLog.login(id, password);

Disconnect from xfServerPlus

If you connected to xfServerPlus using the connect() method, you must disconnect using the disconnect() method. If you have multiple objects sharing a connection, xfServerPlus will not completely close the connection and release the license until all objects are disconnected.

For example:

appLog.disconnect();

See Appendix E: xfNetLink Java Sample Code for a complete JSP code sample.