SQLJ.ALTER_JAVA_PATH stored procedure

SQLJ.ALTER_JAVA_PATH modifies the class resolution path of an installed JAR.

SQLJ.ALTER_JAVA_PATH specifies the class resolution path that the JVM uses when a JAR file that is part of a Java stored procedure references a class that is neither contained in that JAR file, found in the CLASSPATH, nor system-supplied. End of change

SQLJ.ALTER_JAVA_PATH authorization

Privilege set: If the CALL statement is embedded in an application program, the privilege set consists of the privileges that are held by the owner of the plan or package. If the statement is dynamically prepared, the privilege set consists of the privileges that are held by the authorization IDs of the process.

For calling SQLJ.ALTER_JAVA_PATH, the privilege set must include at least one of the following items:

EXECUTE privilege on SQLJ.ALTER_JAVA_PATH
Ownership of SQLJ.ALTER_JAVA_PATH
SYSADM authority

The privilege set must also include the authority to alter a JAR, which consists of at least one of the following items:

Ownership of the JAR
ALTERIN privilege on the schema of the JAR
The authorization ID that matches the schema name implicitly has the ALTERIN privilege on the schema.
SYSADM or SYSCTRL authority

For referring to JAR jar2 in the Java path, the privilege set must include at least one of the following items:

Ownership of jar2
USAGE privilege on jar2
SYSADM authority

SQLJ.ALTER_JAVA_PATH syntax

>>-CALL--SQLJ.ALTER_JAVA_PATH--(--JAR-name1,--+-'path'---+--)--><
                                              +-'blanks'-+      
                                              '-''-------'

path:

   .--------------.   
   V              |   
>>---path-element-+--------------------------------------------><

path-element:

>>-(--+-*------------------------------------+--,--JAR-name2--)-><
      +-Java-package-name--.--*--------------+                    
      '-+----------------------+--class-name-'                    
        '-Java-package-name--.-'

Java-package-name:

                    .------------------------.   
                    V                        |   
>>-Java-identifier----+--------------------+-+-----------------><
                      '-.--Java-identifier-'

class-name:

>>-Java-identifier---------------------------------------------><

SQLJ.ALTER_JAVA_PATH parameters

JAR-name1: A VARCHAR(257) input parameter that contains the DB2® name of the JAR whose path is to be altered, in the form schema.JAR-id or JAR-id. JAR-name1 is the name that you use when you refer to the JAR in SQL statements. If you omit schema, DB2 uses the SQL authorization ID that is in the CURRENT SCHEMA special register.
path: A VARCHAR(2048) input parameter that specifies the class resolution path that the JVM uses when JAR-name1 references a class that is neither contained in JAR-name1, found in the CLASSPATH, nor system-supplied.
During execution of the Java routine, when DB2 encounters an unresolved class reference, DB2 compares each path element in the path to the class reference. If a path element matches the class reference, DB2 searches for the class in the JAR that is specified by the path element.
*: Indicates that any class reference can be searched for in the JAR that is identified by JAR-name2. If an error prevents the class from being found, the search terminates, and a java.lang.ClassNotFoundException is thrown to report that error. If the class is not found in the JAR, the search continues with the next path element.
Java-package-name.*: Indicates that class references for classes that are in the package named Java-package-name are searched for in the JAR that is identified by JAR-name2. If an error prevents a class from being found, the search terminates, and a java.lang.ClassNotFoundException is thrown to report that error. If a class is not found in the JAR, the search terminates, and a java.lang.NoClassDefFoundError is thrown.
If the class reference is to a class in a different package, the search continues with the next path element.
Java-package-name.class-name or class-name: Indicates that class references for classes whose fully qualified name matches Java-package-name.class-name or class-name are searched for in the JAR that is identified by JAR-name2. Class references for classes that are in packages within the package named Java-package-name are not searched for in the JAR that is identified by JAR-name2. If an error prevents a class from being found, the search terminates, and a java.lang.ClassNotFoundException is thrown to report that error. If a class is not found in the JAR, the search terminates and a java.lang.NoClassDefFoundError is thrown.
If the class reference is to a different class, the search continues with the next path element.
JAR-name2: Specifies the DB2 name of the JAR that is to be searched. The form of JAR-name2 is schema.JAR-id or JAR-id. If schema is omitted, the JAR name is implicitly qualified with the schema name in the CURRENT SCHEMA special register. JAR JAR-name2 must exist at the current server. JAR-name2 must not be the same as JAR-name1.

SQLJ.ALTER_JAVA_PATH usage notes

Stored procedures that reference classes in multiple JAR files: A stored procedure that is packaged as a JAR file might reference classes that are in other JAR files, and the referenced JAR files might reference classes in still other JAR files. You need to specify class resolution paths for all dependencies among JAR files that the stored procedure uses. For any JAR files that the stored procedure uses that cannot be found in the CLASSPATH, and are not system-supplied, you need to use SQLJ.ALTER_JAVA_PATH to define the class resolution path. For example, suppose that stored procedure SP, which is packaged in JAR file JARSP, references classes in JAR files JAR1 and JAR2. Classes in JAR file JAR1 reference classes that are in JAR file JAR2. None of the JAR files are in the CLASSPATH or are system-supplied. You need to call SQLJ.ALTER_JAVA_PATH twice, to define the following class resolution paths:

From JARSP to JAR1 and JAR2
From JAR1 to JAR2

SQLJ.ALTER_JAVA_PATH example

Suppose that the JAR file that is named DB2INST3.BUILDPLAN references classes that are in a previously installed JAR that is named DB2INST3.BUILDPLAN2. Those classes are in Java package buildPlan2. The following Java program calls SQLJ.ALTER_JAVA_PATH to add the classes in the buildPlan2 package to the resolution path for DB2INST3.BUILDPLAN.

import java.sql.*; // JDBC classes
import java.io.IOException;
import java.io.File;
import java.io.FileInputStream;
class SimpleInstallJar
{
  public static void main (String argv[])
  {
    String url = "jdbc:db2://sysmvs1.stl.ibm.com:5021";
    String jarname = "DB2INST3.BUILDPLAN";
    String resolutionPath = 
      "(buildPlan2.*,DB2INST3.BUILDPLAN2)";
    try
    {
      Class.forName ("com.ibm.db2.jcc.DB2Driver").newInstance ();
      Connection con = 
        DriverManager.getConnection(url, "MYID", "MYPW");
      CallableStatement stmt;
      String sql = "Call SQLJ.ALTER_JAVA_PATH(?, ?)";
      stmt = con.prepareCall(sql);
      stmt.setString(1, jarname);
      stmt.setString(2, resolutionPath);
      boolean isrs = stmt.execute();
      stmt.close();
      System.out.println("Alteration of JAR resolution path succeeded");
      con.commit();
      con.close();
    }
    catch (Exception e)
    {
      System.out.println("Alteration of JAR resolution path failed");
      e.printStackTrace ();
    }
  }
}