DBL Java configuration

FairCom DB SQL supports stored procedures, triggers, and user defined functions written in the Java language. This chapter explains how to configure the Java environment to take advantage of these features.

Run-Time Settings for Java Stored Procedure Support

FairCom DB SQL requires the Java 1.7 JDK and JRE environment for Stored Procedures, Triggers, and User Defined Functions (UDFs), JDBC, and c-treeDB API Java (FairCom DB SQL V11.0 requires 1.6 or newer). Java is readily available from the Oracle Java downloads website. FairCom DB supports Java on any platform that the Java environment is currently available, including Windows, AIX, Oracle Sun, and Linux.

Check with FairCom for the latest Java compatibility announcements and availability of the latest Java support.

Windows users, see Using Java 1.7 or Later on Windows.

The Java JDK and JRE for many platforms are available at no cost. Click here to download.

Note: 64-bit versions of FairCom DB SQL require a 64-bit version of the JVM to implement stored procedures.

FairCom DB SQL Configuration

Use the following FairCom Server configuration keywords to set your Java environment to take advantage of full stored procedures, triggers, and user-defined functions support.

; JDK environment settings - Be sure to set the JDK to your version.

SETENV CLASSPATH=C:\Program Files\Java\jdk1.7.0_07\jre\lib\rt.jar;C:\FairCom\VX.X.X\win32\bin\ace\sql\classes\ctreeSQLSP.jar (where VX.X.X refers to your FairCom DB version number)

SETENV JVM_LIB=C:\Program Files\Java\jdk1.7.0_07\jre\bin\server\jvm.dll

SETENV JAVA_COMPILER=C:\Program Files\Java\jdk1.7.0_07\bin\javac.exe

The following table lists the Java-related runtime settings needed for the FairCom DB SQL to support Stored Procedures, Triggers and User-Defined Functions. These are required for initializing the JVM within FairCom DB SQL.

Java Related Runtime Settings FairCom DB SQL with JSP

Advanced JVM Configuration

The JVM is loaded into FairCom DB SQL and becomes part of the process when the appropriate configuration options point to a valid Java Runtime Engine (JRE). Stored procedures, triggers, and user-defined functions are executed within this JVM. The JVM environment can be configured and tuned with numerous options. The deployment architect should be familiar with these options from the available Oracle Java documentation.

http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html

The SETENV DH_JVM_OPTION_STRINGS configuration keyword can be used to specify exact parameters for the JVM to use at runtime.

Note: Java stored procedures and triggers developers may take advantage of many different Java features and have wide latitude in creating stored procedure logic. Due to this, it is difficult to make general recommendations, however, information and links are provided below to demonstrate the vast variety of options available.

Different options may be available on different platforms as Java is a highly cross-platform environment.

Heap Memory

One of the most important considerations is memory usage of the JVM. This can result in unexpected memory usage of the FairCom DB SQL process. As the JVM gradually allocates additional heap memory, the process space can grow quite unexpectedly. While Java takes advantage of advanced automatic garbage collection of unused memory references, the triggers for this are many, and in some cases, require careful tuning for the best balance of performance and memory use. Two options of immediate use are the minimum and maximum size of the memory heap.

The JVM defaults to certain proportions of available memory, depending on the OS and if the process is 32-bit or 64-bit.

The initial heap size of the JVM is the following:

• Larger of 1/64th of the machine's physical memory or some reasonable minimum. Before J2SE 5.0, the default initial heap size was a reasonable minimum, which varies by platform.
• If the nursery size (the part of the heap memory reserved for allocation of new objects) is set with -Xns, the default initial heap size will be scaled up to at least twice the nursery size.

You can specify the initial (and minimum) JVM heap size with the -Xms option.

SETENV DH_JVM_OPTION_STRINGS=-Xms:4m

Note: The initial Java heap cannot be set to a value smaller than 8 MB, which is the minimum Java heap size. If you attempt to set it to a smaller value, JVM defaults to 8 MB.

The -Xms value cannot exceed the value set for -Xmx (the maximum Java heap size).

The maximum heap size of the JVM is the following:

• Smaller of 1/4th of the physical memory or 1GB. Before J2SE 5.0, the default maximum heap size was 64MB.

You can specify the maximum JVM heap size with the -Xmx command-line option.

SETENV DH_JVM_OPTION_STRINGS=-Xmx:16m

http://docs.oracle.com/javase/7/docs/technotes/guides/vm/gc-ergonomics.html

Alternative Garbage Collectors

Alternative garbage collectors (GC) are available within the JVM. For particular environments, it may be advantageous to choose an alternate GC for throughput or latency reasons.

• -XX:+UseParallelOldGC (default)
• -XX:+UseConcMarkSweepGC
• -XX:+UseG1GC (New in Java 6 and 7)

Many numerous options are available to tune each of the Java garbage collectors for performance, throughput and low-latency. Check the current Java documentation for your chosen JVM for complete details.

GC Monitoring

It is frequently necessary to examine actual garbage collection statistics. Java garbage collection has many debugging options available for this task. Here is a minimum set to consider:

-Xloggc:<filename>

-XX:+PrintGCDetails

-XX:+PrintGCDateStamps

-XX:+PrintTenuringDistribution

-XX:+PrintGCApplicationConcurrentTime

-XX:+PrintGCApplicationStoppedTime

Monitoring Tools

The JVisualVM utility included with your Java installation is recommended for advanced monitoring of the Java GC process. Load the Visual GC plugin from the "Tools->Plugins" menu.

• See Debugging Java Stored Procedures