|
See Appendix A: Configuration Settings for complete listings of all configuration settings for xfServerPlus and xfNetLink. |
The xfNetLink Java properties file enables you to specify the host name and port number as defaults, set logging and encryption options, and specify various time-out values.
Using a properties file is optional in most cases. If you choose not to use one, you can use the “set” methods associated with each procedural class in your JAR file to specify these values. (See Using a properties file vs. using the “set” methods.) The set methods always take precedence over any entries in the properties file.
|
If you are using Java connection pooling, the xfNetLink Java properties file is required. See Specifying the xfNetLink Java properties file to use for information specific to using the properties file with pooling. |
The table below shows the settings that can be included in the xfNetLink Java properties file. Each is discussed in more detail on the following pages. Because this file is used by Java, these settings are case sensitive.
|
Settings in the xfNetLink Java Properties File |
||
|---|---|---|
|
Setting |
Description |
For more information |
|
xf_RemoteHostName |
(required) Machine where xfServerPlus is running |
|
|
xf_RemotePort |
(required) Port that xfServerPlus is running on |
|
|
xf_DebugOutput |
Value that enables full or error-only client-side logging. |
|
|
xf_LogFile |
Filename that logging output will be written to (rather than stderr) |
|
|
xf_SessionRequestTimeout |
Number of seconds xfNetLink will wait for acknowledgment from the connection monitor in xfServerPlus |
|
|
xf_SessionConnectTimeout |
Number of seconds xfNetLink will wait for acknowledgment from the logic server in xfServerPlus when running in normal mode |
|
|
xf_DebugSessionConnectTimeout |
Number of seconds xfNetLink will wait for acknowledgment from the logic server in xfServerPlus when running in debug mode |
|
|
xf_SessionLingerTimeout |
Number of seconds xfNetLink will wait for a return from a remote call |
|
|
xf_SSLCertFile |
The path and filename of the keystore file to use for encryption |
|
|
xf_SSLPassword |
Password associated with the keystore file |
|
Creating and naming a properties file
There is a sample xfNetLink Java properties file named xfNetLnk.ini included in the Examples directory that is part of the xfNetLink Java distribution. You can edit and use the sample file or create your own file in a text editor.
If you name your properties file “xfNetLnk.ini” and place it in the directory that your Java application starts in or in the default location required by your web server and servlet container, you can use the default constructor when you instantiate an object.
If you name your properties file something other than “xfNetLnk.ini”, you must use the “ini file” constructor and pass the name of the properties file when you instantiate an object.
For details on using the default and ini file constructors, see Instantiate an instance of a procedural class.
|
To include comments in the properties file, precede the comment with a number sign (#). |
Using a properties file vs. using the “set” methods
As mentioned above, you can specify properties either in the xfNetLink Java properties file or by using the set methods. It is also possible to combine the two methods, specifying some properties in the file and setting others with the set methods, or setting them in both ways. If both a property and its corresponding set method are specified, the set method take precedence. Use caution if you implement this approach; it can result in confusion and be difficult to troubleshoot.
The table below lists the xfNetLink Java properties file settings and their corresponding set methods. As you can see, there are three time-out settings available in the properties file for which there are no corresponding set methods. If you wish to set these time-outs, you must use a properties file. Conversely, the setSSLSecCompliance() method has no corresponding properties file setting; to override the program default, you have to call the set method,
|
Properties File Settings and Corresponding “set” Methods |
|
|---|---|
|
Properties file setting |
Set method |
|
xf_RemoteHostName |
setxfHost() |
|
xf_RemotePort |
setxfPort() |
|
xf_DebugOutput |
setxfLogging() setxfExceptOnly() |
|
xf_LogFile |
setxfLogfile() |
|
xf_SessionRequestTimeout |
N/A |
|
xf_SessionConnectTimeout |
N/A |
|
xf_DebugSessionConnectTimeout |
N/A |
|
xf_SessionLingerTimeout |
setxfCallTimeout() |
|
xf_SSLCertFile |
setSSLCertFile() |
|
xf_SSLPassword |
setSSLPassword() |
|
N/A |
setSSLSecCompliance() |
If your client application uses JavaServer Pages, keep in mind that you can have only one xfNetLink Java properties file. Most servlet containers require that the properties file be located in the container’s root directory. Because all objects use the properties file from the root directory, if you wanted, for example, to use different host and port settings for development vs. production, you would need to use the set methods.
If your client application is a standard Java application, the properties file must be located in the directory from which the application is started. This means that you could have several Java applications located in different directories, each with its own properties file.
The set methods always override settings in the properties file. When you use the default constructor, it preloads the following settings from the xfNetLnk.ini file:
xf_RemoteHostName
xf_RemotePort
xf_DebugOutput
xf_LogFile
xf_SSLCertFile
xf_SSLPassword
After an object is instantiated, if any of these items is set with the corresponding set method, the set method value will override the preloaded value. The preloaded values will continue to be used if there is not an override set with a set method. Note that any values set with the set methods stay in effect only for that object. When you instantiate another object, it may use different values.
Specifying the host name and port number
Specifying the host name and port in the xfNetLink Java properties file enables the Java object to read them as defaults. Using the properties file for the host name or port number is optional; you can also set them as properties of the class.
Setting the host name and port is required. (Note that the default port for xfServerPlus is 2356. Even if you use this default, you must still specify it on the client.)
To specify the host name and port as defaults
In the xfNetLink Java properties file, specify the host name of the machine on which the xfServerPlus service is running and the port number on which it is listening. The port number must be an integer. Neither value can be null. I
For example:
xf_RemoteHostName = elmo xf_RemotePort = 2356
Specifying logging options
You can specify full or error-only client-side logging. By default, information is output to stderr (standard error). Alternatively, it can be written to file using the xf_LogFile property. If the specified file cannot be opened for writing, an error is displayed and the information is output to stderr. For details on the information logged, how log files are named, and a sample log, see Using client-side logging.
During development, full logging can be useful; in a production environment we do not recommend setting full logging. Rather, for production, we recommend error-only logging. For either logging level, we recommend that you always write output to a log file.
|
|
If your client application is not attached to a terminal (e.g., JavaServer Pages), output to stderr will not be visible; use the xf_LogFile property to write output to file. |
To specify client-side logging
| 1. | In the xfNetLink Java properties file, set the debug output property to one of these values: |
true = full logging
error = error-only logging
false = no logging (the same as not setting it)
For example,
xf_DebugOutput = true
or
xf_DebugOutput = error
| 2. | To specify that the output be written to file instead of going to stderr, specify a filename. For example, |
xf_LogFile = c:\\work\\Myfile.log
will direct the packet logging (if full logging is specified) and most exceptions to the file Myfile.log and the method and parameter logging to a file named MyfileJCW.log. (See Using client-side logging for details on these two log files.) These files will be created if they do not exist; if the files already exist, additional material is appended to the end. To place the files in a specific location, specify the full path name, using double slashes as shown in the example above. If you do not specify a path, the files are created in the current working directory.
Specifying time-out values
You can specify three types of time-outs in the xfNetLink Java properties file, as illustrated in figure 1, below.
|
|
The request for session time-out (‘A’ in figure 1) measures the time that xfNetLink will wait to receive the initial acknowledgment from the connection monitor within xfServerPlus. The connection monitor is responsible for accepting session requests from xfNetLink and signaling the logic server to start a session.
The request for session time-out is measured from the time xfNetLink sends the request for a connection to the time xfNetLink receives the acknowledgment back from xfServerPlus. The default value is 120 seconds.
To specify a request for session time-out
In the xfNetLink Java properties file, specify a value in seconds for xf_SessionRequestTimeout. For example, to specify a 5-minute time-out, use
xf_SessionRequestTimeout = 300
If the session request time-out value is invalid (less than zero, blank, or alpha), the default is used.
Once the initial socket communication is established (‘A’ in figure 1), the connection monitor signals the logic server to start a session. The connect session time-out (‘B’ in figure 1) is measured from the time that xfNetLink receives the acknowledgment from the connection monitor to the time it receives an acknowledgment from the session started by the logic server in xfServerPlus.
This time-out is set separately for normal operation and debug operation. The default value for normal operation is 120 seconds; for debug it is 600 seconds. You will probably want to set the debug time-out to a greater value than the normal time-out since you need to move from one machine to another when starting a debug session (see the important note under step 2 in Running in debug mode on Windows and Unix).
To specify a connect session time-out
In the xfNetLink Java properties file, specify a value in seconds for xf_SessionConnectTimeout and/or xf_DebugSessionConnectTimeout. For example, to specify a 3-minute time-out for normal operation and a 6-minute time-out for debug operation, use
xf_SessionConnectTimeout = 180 xf_DebugSessionConnectTimeout = 360
If either of the connect session time-out values is invalid (less than zero, blank, or alpha), the corresponding default value is used.
|
|
The xf_DebugSessionConnectTimeout setting applies only when you use the debugInit() and debugStart() methods to run an xfServerPlus session in debug mode. |
The call (session communication) time-out (‘C’ in figure 1) measures the length of time that xfNetLink waits for a return from a remote call. This time-out is measured for each send–receive request between xfNetLink and xfServerPlus. The default value is 1800 seconds (30 minutes).
To change this value after an object is instantiated, use the setxfCallTimeout() method. See Setting a call time-out programmatically. You can also set a call time-out value for xfServerPlus. See SET_XFPL_TIMEOUT.
To specify a call time-out
In the xfNetLink Java properties file, specify a value in seconds for xf_SessionLingerTimeout. For example, to specify a 10-minute time-out, use
xf_SessionLingerTimeout = 600
If the call time-out value is invalid (less than zero, blank, or alpha), the default value is used.
Specifying encryption options
These options are used to specify the certificate file and its password. If these values are present in the properties file, they are used instead of the defaults. You can override these values at runtime with setSSLCertFile() and setSSLPassword(). The setSSLSecCompliance() method is available to override the built-in security compliance level. (There is no properties file setting for it.) See the Method reference for information on the set methods. See Using xfServerPlus encryption for more information on implementing encryption.
To specify a certificate file and password
In the xfNetLink Java properties file, specify the full path and filename of the certificate file. The default value is the cacerts file located in the java.home\lib\security directory, where java.home is the JRE installation directory. (But note that we recommend against using this file, as it will be overwritten any time Java is updated.) For example,
xf_SSLCertFile = c:\\java\\jre6\\lib\\security\\myCertFile
The default password is “changeit”. Use xf_SSLPassword to specify a different password. For example,
xf_SSLPassword = myFavPassword
To specify the security compliance level
The security compliance level indicates the protocols to be used for encryption. You cannot specify this value in the properties file. If you want to override the system default, you must use the setSSLSecCompliance() method. See the Method reference for more information on setSSLSecCompliance().
