CAA V5 Authorized API Identification, Usage, Deprecation, and Stability

Rules and Standards	CAA V5 Authorized API Identification, Usage, Deprecation, and Stability Understanding CAA Authorized API mechanisms and tags
Technical Article

Abstract

This article gives you rules regarding CAA Authorized API qualifiers and usage.

CAA Authorized APIs
CAA Authorized API Qualifiers
CAA Authorized API Deprecation
CAA Authorized API Stability
CAA Authorized API Additional Tags
CAA Authorized APIs Required by Your Application
CAA Authorized and Deprecated API, and DS Internal Resource Processing

CAA Authorized APIs

V5 configurations and products may include Authorized APIs that can be used to create client applications. The APIs authorized by a configuration or a product are located in the PublicInterfaces directories of one or several frameworks of the configuration or the product. Additional APIs may be found in these directories, for example:

To close the set of Authorized APIs with some DS Internal Resources from the #include statement standpoint
To enable code generated by different tools to build.

Client applications can use only CAA Authorized APIs tagged using CAA Authorized API qualifiers. These qualifiers help to distinguish them from the others supplied only for build purpose. In addition, some Authorized APIs, such as classes or interfaces, may be only partially authorized. For example, a class may authorize only a subset of its methods. As a CAA developer, to know what you can use, you can either:

Refer to the CAA Authorized API reference part of the CAA Encyclopedia:
- The C++ API reference
- The Automation API reference
- The Java API reference
Refer to the C++ or IDL header files, and interpret the CAA Authorized API qualifiers and tags, as described below.

Remember that what is NOT documented in the CAA Encyclopedia is a DS Internal Resource and CANNOT be used in a client application.

Java APIs do not include CAA Authorized API qualifiers. Only documented Java APIs are authorized and can be used.

[Top]

CAA Authorized API Qualifiers

These qualifiers are located at the top of the file and enclosed in a /** */ comment. Below is an example of such tags:

#ifndef CATTopologicalBlend_H
#define CATTopologicalBlend_H
// COPYRIGHT DASSAULT SYSTEMES 1999
/**
 * @CAA2Level L1
 * @CAA2Usage U1
 */

The meaning of these qualifiers is:

`@CAA2Level L1`	Marks the header as an Authorized API
`@CAA2Usage U1`	Defines the header intended usage. Valid values range from U0 to U6

Value	Meaning	Aim	Comment
L0	Authorized API	Provides Customers, Business Partners, and Adopters with Authorized APIs for beta testing Provides Authorized APIs to be qualified as L1 in next releases to enable a validation/evaluation process.	No compatibility is insured - but usage is allowed May change or disappear without any warning No documentation is provided
L1	Authorized API	Provides Customers, Business Partners, and Adopters with reliable APIs to use to develop applications	Build time compatibility is insured between releases, except if the Authorized API was deprecated two releases before Run time compatibility is insured between SPs of the same release A documentation is provided.

The usage of a header file depends on its intended use in the client application.

Value	Usage Meaning
U0	Usage not yet specified. Reserved for L0 Authorized APIs. Nevertheless, L0 Authorized APIs can have a specified usage ranging from U1 to U6.
U1	Concrete class: use as is only. C++ usage The common usage is to either instantiate the class or retrieve an existing pointer to an instance of that class, and call its methods.
U2	Concrete class: may be derived. C++ usage The common usage is to create a new class that derives from this class, possibly reimplement some of its methods, and add new methods. Then it can be used in the client application.
U3	Interface: cannot be re-implemented, use as is only. C++ and IDL usage The common usage is to retrieve a pointer to this interface onto a CAA component that implements it, and call its methods.
U4	Interface: can be re-implemented with a DS adapter. C++ usage The common usage is to implement this interface onto a client component, usually in an C++ extension class, by deriving the DS adapter, that is, the class provided by DS to be derived for this purpose. This class has a U2 usage, and provides the interface method implementations. Only a subset of the interface methods needs to be implemented, the remainder being implemented by the DS adapter. Usually, only the methods to implement are documented. U4 usage is followed by the adapter to use. For example, the CATIEdit interface must be implemented by a class that derives from the adapter CATExtIEdit: /** * @CAA2Level L1 * @CAA2Usage U4 CATExtIEdit */
U5	Interface: must be totally re-implemented. C++ usage The common usage is to implement all the interface methods onto a client component.
U6	Interface: must be derived. C++ usage The common usage is to create an interface that derives from this interface without adding new methods, and to implement the derived interface. This is for example the case of a workbench or add-in exposed interface.

[Top]

CAA Authorized API Deprecation

When a CAA Authorized API becomes obsolete, it is deprecated. Although this should be exceptional, the number of the CAA Authorized API makes it happen more frequently than wished. The deprecation process runs as follows:

Deprecation takes place for C++, Automation, and Java APIs
A deprecated API can be any Authorized API (class, interface, method, global function, enum, structure, #define or macro, and so on)
An Authorized API is deprecated starting from the General Availability (GA) of a new V5 release, and never starting from a Service Pack (SP)
A deprecated API remains available during a two-release life time starting from the one for which it is deprecated.
For example, an Authorized API deprecated starting from V5R11 will remain available without modification during the whole V5R11 and V5R12 life times.
A deprecated API shows its replacing Authorized API that client applications must use instead. This replacing Authorized API is of course available at the deprecation time. The two-release life time is dedicated to CAA developers to modify their client applications using the replacing Authorized API. Deprecated APIs are available from the CAA Encyclopedia that includes a deprecated index for each API language:
- The CAA C++ API Deprecated Index
- The CAA IDL API Deprecated Index
- The CAA Java API Deprecated Index
A deprecated API issues a warning when client application modules that contain it are rebuilt
A deprecated API is removed from the CAA Authorized APIs two releases after the one it was deprecated.
For example, an API deprecated starting from V5R11 will be removed on V5R13 GA.

[Top]

CAA Authorized API Stability

Client application compatibility depends on CAA Authorized API stability between SPs and releases.

CAA Authorized APIs are checked in a such a way that:

They are run time compatible between the Service Packs (SPs) of a given V5 release.
This means that client applications don't need to be rebuilt on SPs.
They are build time compatible between two subsequent V5 releases, as far as the deprecation process doesn't take place.
This means that client applications must be rebuilt on new V5 releases without code changes, except if Authorized APIs tagged as deprecated are used in the client application and if it was deprecated from more than two releases. Warning are issued when rebuilding the application for each deprecated API found. See CAA Deprecation.

Run time compatible possible modifications between two successive SPs:

Add new classes and interfaces
For U1 "Use as is" classes: add new concrete public methods
For U2 "may be derived" classes: add new concrete, public or protected methods
For both U1 and U2 classes: add, modify, or remove concrete private methods
For interfaces: nothing

Build time compatible possible modifications between two successive releases:

Same as above PLUS:
Declare classes / interfaces / methods as deprecated provided that the function is replaced with another one
Remove or de-expose deprecated APIs after two releases.

[Top]

CAA Authorized APIs Additional Tags

When scanning the header files, you may find two CAA tags in the comments located above any entity, such as class, interface, enum, typedef, #define or macro, or structure declaration, or global function or method prototype, that locally resets for that entity the CAA Authorized API qualifiers set for the header file. These two tags are:

Tag

Meaning

@nodoc

Do not use
This depicts a DS Internal Resource. Its usage is prohibited.

@deprecated

Do not use any longer
This means that the API was authorized, but will be removed. See CAA Authorized API Deprecation. The tag syntax is as follows:

/**
 * @deprecated V5R11 CATBaseUnknown
 * ...

V5R11 means that the Authorized API is deprecated starting from V5R11, and that the replacing API is CATBaseUnknown. Its usage is prohibited starting with V5R13.

[Top]

CAA Authorized APIs Required by Your Application

The CAA Authorized APIs are supplied by configuration and products:

A run time configuration or product is protected by a license (MD2 for instance). This license authorizes parts of the V5 frameworks that make up the configuration or product. The CAA part of this configuration or product is made up of the sub-set of those frameworks containing at least a CAA V5 Authorized API.
A CAA V5-based application or product intended to be compatible with a given run time license must be developed on top the previous sub-set.
This CAA V5-based application or product must be executed in an environment that exactly contains this run time license.

To determine which CAA Authorized API are required by your application, go to the CAA Internet site. Register if you have not done it already, and go to the Developer's C++ & Java home page. Click CONFIGURATION CONTENTS in the left frame, and select a V5 release, a media, and a configuration or a product to know which frameworks it supplies.

[Top]

CAA Authorized and Deprecated API, and DS Internal Resource Processing

The RADE tools process differently the CAA Authorized APIs, CAA Deprecated APIs, and DS Internal Resources.

CAA Authorized API Processing

Domain	Build	Documentation	Unauthorized Symbols	Stability Checking
Behavior	No warning is generated, except if the API is deprecated.	Authorized APIs appear in the CAA V5 Encyclopedia.	Authorized APIs are not stored within the "Unauthorized symbols" database.	A build time stability is insured between releases, except if the Authorized API was deprecated two releases before. A runtime stability is insured between SPs or the same release: no change is allowed within a release.

[Top]

CAA Deprecated API Processing

Domain	Build	Documentation	Unauthorized Symbols	Stability Checking
Behavior	No warning is generated, except if the API is deprecated.	Deprecated APIs appear in the CAA V5 Encyclopedia as deprecated, and show up their replacing Authorized API.	Deprecated APIs are not stored within the "Unauthorized symbols" database.	A build time stability is insured between releases, except if the Authorized API was deprecated two releases before. A runtime stability is insured between SPs or the same release: no change is allowed within a release.

[Top]

DS Internal Resource Processing

The DS Internal Resources usage is prohibited.

Domain	Build	Documentation	Unauthorized Symbols	Stability Checking
Behavior	Warnings are displayed to the developer, but the library is built. An invalid library is refused at run time.	DS Internal Resources do not appear in the CAA Encyclopedia.	DS Internal Resources are stored within the "Unauthorized symbols" database.	No stability check is insured.

[Top]

History

Version: 1.0 [Jan 2000]	Document created
Version: 1.1 [Nov 2000]	L0, L2, U6, U7 notions added.
Version: 1.2 [Dec 2000]	U8 notion added.
Version: 1.3 [Aug 2002]	L2, U7, U8 notions removed.
Version: 1.4 [Feb 2003]	Deprecation, stability notions, additional tags, and required APIs added
Version: 1.5 [Feb 2004]	Authorized APIs and DS Internal Resources added
[Top]

Rules and Standards