API Guidelines

UNDER CONSTRUCTION

Introduction

Pentaho's public application programming interfaces (APIs) form a programming contract between Pentaho and Embed customers, plugin developers, and community contributors. Therefore it is very important that proper procedures are followed anytime API methods are changing or being removed.

Extending existing APIs

When a new method is to be added to an API, the following procedure should be followed in order to minimize immediate impact, as well as to give a clean path forward for updating the API.

API Extension Procedure

1. If there is no existing JIRA case that provoked the API change request, create a JIRA case proposing the extension.
   1. If relevant, provide links to the superseding APIs in the Jira case.
   2. Assign the case to the governing architect.
2. Send notification of the case to the team leads / architects involved with the affected project.
3. Implementation of extension to interface XYZ
   1. Create a new child interface called XYZExtended (if it does not already exist) that extends XYZ, add the new method(s) to XYZExtended.
   2. Where the existing method is called, add an "instanceof" check. If true, cast and delegate. If not, retain the current behavior
   3. @Deprecate the existing interface, with lots of detail in the javadoc (see the guidelines here)
   4. Document the new interface, usage, deprecation of the old, etc. in the appropriate locations
4. If there's agreement to proceed, make the change.
5. The architect should then work with PM and other stakeholders to determine how long the deprecated features should be supported.
6. Keep the case open and set the fix version for the next major release when there's agreement that the deprecated features can be removed

General Guidelines

1. Deprecated features need to continue to work!!
2. Tests involving the deprecated features must not be removed. If there are superseding features, they need to be tested in addition to the deprecated ones.
3. Deprecated items should be preserved until the next major release at the least.

Java Deprecation

1. Use both the @Deprecated annotation on the affected Class / Method / Field to generate compiler warnings, as well as @deprecated inside the javadoc comment
2. There should be a short sentence immediately following the @deprecated javadoc tag explaining when and why it's deprecated.

   /**
    * @deprecated As of release 6.0, use {@link Clazz#method()} instead
    **/
   void verify();
   

   
   
3. Optionally, if there needs to be more description, the paragraph following @deprecated will also be associated with the deprecation tag and presented appropriately in the Javadoc

   /**
    * @deprecated As of release 6.0, no longer needed.
    * Calls to verify will do nothing as of the 5.1 release. Verification happens as part of the connect
    * method. You can safely remove these calls
    **/
   void verify();
   

   
   
4. If the replacement API usage is not as simple as a method/class name change covered by a {@link}, then the paragraph following the @deprecated tag should include a code snippet showing the new API usage.

   /**
    * @deprecated As of release 6.0.
    * This class has been replaced by the non-blocking version {@link foo.Clazz}
    * Usage:
    * <pre>
    *   Clazz newClass = Clazz.newInstance();
    *   Future future = newClass.doSomethingInteresting();
    * </pre>
    **/
   void OldClazz();
   

   
   

Service Deprecation

Enunciate will use the Javadoc comments in its generated documentation.

1. The deprecated service methods should log at the WARN level to alert system admins of deprecated service usage

Javascript Deprecation

1. console.warn the deprecated modules / functions with comments similar to Javadoc. Reference the replacements where possible.
2. AMD Modules
   Warn inside the define not outside, so it flags actual usage vs loading :

   define( 'common-ui/someModule', function(){
     console.warn( "Deprecated: as of 6.0. Use the common-ui/BetterOne module instead." )
     return { ... }
   }
   

   
   
3. Functions

   function pentahoGet(){
     console.warn( "Deprecated: pentaho-ajax.js#pentahoGet is deprecated as of 6.0. Use the 'dojo/Request' module instead." )
   }
   

4.