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 different SDK toolkit libraries with developed Application code , against a different version of the IBM Cognos BA Server , including Framework Manager or Transformer Cube Desginer.

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 (Obsolete)
- 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 - Do Not Use this combination anymore.
axis.jar
axisReportNetClient.jar (Obsolete) 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() instead.
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 Development Guide to write your code, while in Cognos 10 you would used the C10 SDK Development Guide.
There are changes between these two major versions in Methods and how thing work, therefore you should always upgrade your code to the latest version and standards.

SET3
cognos-axis.jar
cognosClient.jar This named combination set is ONLY for applications that use other similar library jars, which may interfere with the normal jars for Cognos 8 / 10 like in the SET1 .
They contain a renamed path, so that all methods begin with com.cognos.xxx.yyy ..... etc. This will avoid the library contention and clashing of methods, which otherwise would result in major errors with java stacktraces.
This is the recommended set to use with SDK applications software to work properly with application servers, different Tomcat installations, ® SAP Netweaver, ® Websphere, ® Weblogic and ® JBoss installations.

Additional Notes:

Calls for assistance with the SDK and PMR Tickets that you log with IBM Cognos Support and the SDK Team will have a much shorter resolution time if the advise in this document is followed.

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 exists in your classpath or in the Development or RunTime Environment.
The SDK libraries for Cognos 8 or 10 are in the ../SDK/java/lib product folder path only.

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 however strongly advised to change the source to include the right naming convention, and not to use CRN or C8 for Cognos 10 code 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

Document information


More support for:

Cognos Business Intelligence
Software Development Kit

Software version:

8.4.1, 10.1, 10.1.1, 10.2, 10.2.1, 10.2.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

Content navigation