SDK - How to use the SDK Libraries including Axis Jar files in a software application.

Technote (FAQ)


Question

The SDK product contains a set of libraries in the ../sdk and ../sdk/java/lib folder.
There are five different style of Axis library jar files in the IBM Cognos SDK/java/lib folder.
Why are they different and when should they be used in any application ?

Also, what happens with IBM Cognos 8 SDK libraries, if Axis 1.4 is being used for other applications running in the same environment ?

Answer

First a important statement for any SDK developed Application from the SDK Software Developers Guide :

"Applications must be compiled on the same version of the IBM Cognos Software Development Kit as that used by the IBM Cognos Business Intelligence environment that you intend to deploy your applications in."

This should explain why it is not supported , to use a specific SDK toolkit libraries with Application code that uses these, against a different version of the IBM Cognos BI Server or Framework Manager.

Axis Version used in IBM Cognos BI :
The IBM Cognos 8 Systems are based on Apache Axis 1.1 version.
The IBM Cognos 10 Systems are based on Apache Axis 1.4 version.

Currently the SDK Product contains five Axis related Jar files in the <cognos>/sdk /java/lib Library directory, beside other Jar files that are included in the SDK product.

- axis.jar
- axisCognosClient.jar
- axisReportNetClient.jar
- cognos-axis.jar
- cognosClient.jar

The axis.jar included with the SDK is not the original Apache Axis 1.1 or 1.4 library, but is an IBM Cognos modified version needed by IBM Cognos BI Systems.
The axisCognosClient.jar file contains the IBM Cognos SDK API; it calls this axis.jar library for its functionality.

If an application developer wants to use a higher version of axis for other application running together with IBM Cognos 8 SDK applications , - for example Axis 1.4, then a conflict will appear.
This is because the IBM Cognos 8 SDK cannot work with Axis 1.4, but only with Axis 1.1 as supported version.

The same applies with IBM Cognos BI 10, which is based on Axis 1.4, and using a different Axis for the running environment.

To avoid this Apache Axis conflict, two other jar files are provided in the lib directory, which have a different path in them :

File cognos-axis.jar, which is identical to the provided axis.jar, and File cognosClient.jar, identical to axisCognosClient.jar.
Both of these have an internal path of "com.cognos.org.apache" instead of "org.apache", and as such are made unique for IBM Cognos SDK.

To be able to use another version of axis, the following changes are needed, so that IBM Cognos SDK continues to use either the axis 1.1 or axis 1.4 dependent on the version of IBM Cognos :
1. In the CLASSPATH, replace axis.jar by the cognos-axis.jar
2. In the CLASSPATH, replace axisCognosClient.jar by cognosClient.jar
3. In the SDK code, add com.cognos. in front of org.apache in all the lines starting with import org.apache.axis.

Example import path in Java code :
import com.cognos.org.apache.axis.client.Stub;

In the case when more than the above two axis.jar are used, sometimes the following error appears that shows there is a Jar conflict problem :

Exception in thread "main" java.lang.ClassCastException: com.cognos.developer.schemas.bibus._3.ContentManagerServiceStub incompatible with org.apache.axis.client.Stub

An explanation on the three IBM Cognos SDK important sets of libraries and where you should used them, note that these "sets" are mutually exclusive and can not be used together :

SET1
axis.jar
axisReportNetClient.jar This named combination set is ONLY for ReportNet 1.0 and 1.1 Development.
Recommendation : When developing in IBM Cognos SDK 8 or 10, the library axisReportNetClient.jar should no longer be loaded or used, and source code should be Re-Written according to the SDK Developer Guide delivered with the Product version.

It is also advised to change the SDK source code to no longer include CRN style of naming conventions, and not use existing Cognos Method names for your own classes.
For example, do not use CRNConnect(), but instead use C10Connect() if needed.
Your own classes() should have unique names for your company.

SET2
axis.jar
axisCognosClient.jar This named combination set is ONLY for IBM Cognos 8 / 10 Development
When in Cognos 8 - use the C8 SDK Devel Guide to write your code, while in Cognos 10 you would used the C10 SDK Devel Guide.
There are changes between these two major versions in Methods and how thing work, therefore you should upgrade your code.

SET3
cognos-axis.jar
cognosClient.jar This named combination set is ONLY for applications that use other jars, which may interfere with the normal jars for Cognos 8 / 10 as in set 2 above
They contain a renamed path, so that all methods begin with com.cognos.xxx.yyy ..... etc. avoiding library contention and clashing of methods.
It is the recommended set for use with SDK software in other application servers than IBM Cognos tomcat.

In your application development you should be using only either of SET2 or SET3 for Cognos 8 / 10, and never SET1. Because of the mutual exclusivity, it is needed that only one "Set" of libraries is in your classpath or in the Development Environment.
The SDK libraries for Cognos 8 or 10 are in the ../SDK/java/lib product folder path only.

Additional Notes:

1. The inclusion of axisReportNetClient.jar is for previous IBM Cognos ReportNet SDK users who may want to keep the path in the developed code the same name as it is in Cognos ReportNet. The files axisReportNetClient.jar and axisCognosClient.jar have exactly the same content.
It is advised to change the source to include the right naming convention, and not to use CRN naming anymore.

Using ReportNet document style of coding is a constant source of misunderstanding and potential problems within IBM Cognos Support, and it is advised to change your Application Source to a more generic style, having no longer ReportNet, CRNConnect or Cognos 8 or 10 style of naming convention for your own methods.

In Cognos 10.2 all CRN methods were deprecated and are no longer included with the product, and without changes to the new libraries, or a more generic style, your previous coded applications will no longer work.
A further note for C10.2 is that the IBM Cognos Server specific Axis Libraries placed in the ../webapps/p2pd/WEB-INF/lib folder can not be used for SDK Development, as they are much different than the SDK Axis Libraries.

IBM Cognos SDK Support does not recommend to attempt to develop SDK code with these libraries.


Related information

SDK - Is it possible to use a different version of axis
SDK - Product information and Upgrading Software Develo

Cross reference information
Segment Product Component Platform Version Edition
Business Analytics Cognos Business Intelligence Software Development Kit Windows 8.3, 8.4, 8.4.1

Rate this page:

(0 users)Average rating

Add comments

Document information


More support for:

Cognos Business Intelligence
Software Development Kit

Software version:

8.3, 8.4, 8.4.1, 10.1, 10.1.1, 10.2

Operating system(s):

AIX, HP Itanium, HP-UX, Linux, Solaris, Windows

Software edition:

Edition Independent

Reference #:

1441931

Modified date:

2010-07-23

Translate my page

Machine Translation

Content navigation