Migrating to BBJ 19.10

SSCP Changes

BBj 19.10 introduces an updated ClassLoader, which includes the following updates and improvements to Session-Specific Classpaths:

• SSCPs can specify a single parent SSCP, allowing them to have a hierarchical structure. A parent must be the first entry in an SSCP definition as displayed in the Enterprise Manager’s BBj Services > Java > Classpath display. A parent SSCP will be expanded in place to a list of its jar files.
• SSCPs can also include other SSCPs by adding them through the Enterprise Manager.
• The bbj_default SSCP is the SSCP used by default  when the -CP<SSCP> argument is not specified when running the BBj Interpreter. This special SSCP is fully configurable. By default, it contains only the bbj_internal classpath.
• The bbj_internal SSCP contains the classpath used by BBj internally. It is not configurable by the user but may be included in other classpaths to easily add the bundle of JARs defined within it.

Dependence on bbj_internal

Prior to BBj 19.10, all BBj interpreter sessions, including those that specified an SSCP, inherited the classpath that BBj used internally by default. Now, BBj’s JAR dependencies are captured in the bbj_internal SSCP. The bbj_internal SSCP identifies the BASIS JARs that BBj requires. It also captures BBj’s third-party dependencies by including the BBjIndex.jar and ExtIndex.jar files.

Some SSCPs created before 19.10 may now require explicit inclusion of JARs found in the bbj_internal SSCP. For these SSCPs to continue to function as expected, it may suffice for you to manually set the bbj_internal SSCP as the parent SSCP. This will allow your classpath to continue inheriting all of the JARs used by BBj.

However, it is strongly recommended that you determine the specific JARs that your SSCP depends on and include them separately, in order to avoid any direct dependence on bbj_internal. The bbj_internal SSCP can change without warning as BASIS updates, removes, or adds JAR files as necessary for internal use.

Using bbj_default

The bbj_default SSCP is the default classpath used when no classpath is specified and is entirely configurable and customizable. By default, its value is set to bbj_internal as the first and only entry so that it inherits the JARs from bbj_internal as its parent. This is purely a convenience for backward compatibility, and it is not necessary to continue to use bbj_internal within the bbj_default definition if you do not rely on it.

If you work with different SSCPs for different applications, bbj_default may serve as a convenience during development by allowing you to change its value on-demand depending on which SSCP you are currently working with. In such a case, it is easiest to maintain separate custom SSCPs and to simply set the parent of bbj_default to the SSCP you are working with, so that bbj_default is a copy of that SSCP. This method allows you to change the default SSCP quickly.

If you only need or use a single SSCP, bbj_default can also be edited directly to include the JARs you need without creating any other SSCPs.

Using a Different Version of a JAR

You may wish to use the JARs from bbj_internal (or another custom SSCP) but change one or more of them to use a different version. In a case like this, it is important to know that SSCPs are loaded sequentially in such a way that the first occurrence of a JAR will take precedence over any later ones. This means that you may first include the JAR file you wish to use, and then include bbj_internal after it. The JAR file you specified will overrule the one specified within bbj_internal, and the rest of the JARs will still be included.

However, note that since bbj_internal is not the first entry, it will no longer be the parent of this SSCP, which can cause namespace issues if you are attempting to share objects or functions between programs that use separate SSCPs.

Sharing Objects with Separate SSCPs

If you wish to share objects or functions between programs, they must not only use the same JAR file, but the JAR must be listed in the same SSCP. The most straightforward way to ensure that object definitions match is for the two programs to use the same SSCP. If this is not possible, then they must inherit the object definitions from the same parent SSCP. If two programs use the same JAR file in their separate classpaths and do not inherit it from a parent SSCP, the object and function definitions will not match.

SQL Custom Function Updates

If you currently use custom scalar functions, group functions, or date formats, they may no longer be compatible with the update to BBj 19.10. See the following documentation for information on how to configure SQL custom functions in 19.10 and higher:
https://documentation.basis.cloud/BASISHelp/WebHelp/b3odbc/sql_custom_functions.htm

Summary

In summary, here are the key points to be aware of:

1. Prior to BBj 19.10, BASIS did not ship any SSCPs because all BBj interpreter sessions, including those that specified a custom SSCP, inherited the classpath that BBj used internally by default. This had two drawbacks:
   1. For BBj’s internal use it was, and is, necessary for BASIS to occasionally update, remove, or add JAR files from the internal classpath. This had the potential to negatively impact customers’ applications that may have purposely or inadvertently relied on BBj’s internal classpath.
   2. Customers who wished to use a different version of the classes that BBj used internally were not able to easily do so.
2. From BBj 19.10 onward, BBj interpreter sessions do not automatically inherit the classpath that BBj uses internally except as described below in 3 (d). This overcomes the drawbacks previously mentioned but has the potential to break applications that relied on having access to BBj’s internal classpath.
3. To mitigate the potential problem above, BASIS has provided the following enhancements to SSCPs, including shipping two pre-configured SSCPs with BBj called bbj_internal and bbj_default:
   1. ​SSCPs now support a hierarchical structure allowing other SSCPs to be referenced within an SSCP.
   2. bbj_internal is a non-configurable SSCP that contains the classpath used by BBj internally.
   3. Customers can include a reference to the bbj_internal SSCP in their own custom SSCPs in order to preserve access to BBj’s internal classpath.
   4. For convenience and to provide backward compatibility, bbj_default is provided as a fully configurable SSCP that all BBj interpreter sessions will use when the -CP<SSCP> argument is not specified on invocation of BBj. This SSCP currently ships with a single entry referencing the bbj_internal SSCP.
4. BASIS strongly recommends that you replace the reference to the bbj_internal SSCP in all your SSCPs, including bbj_default, to reference the specific JARs in BBj’s internal classpath that your application depends on. Include them separately in all SSCPs in order to avoid any direct dependence on classes being available in bbj_internal. The bbj_internal SSCP can change without warning as BASIS updates, removes, or adds JAR files as necessary for internal use.
5. Customers who wish to use a different version of the classes that BBj uses internally are now able to easily do so.