qooxdoo supports deprecating different structures in the code. This page describes how to handle the scenarios of deprecation and what can be deprecated and what not.

One common scenario is the deprecation of methods. The three typical use-cases are listed in the following subsections.

Deprecating methods because they will be removed or replaced is one of the easiest tasks. You have to do two things:

• Mark the method as deprecated in the API documentation.

/**
 * ...
 * @deprecated
 */

• Print out a deprecation warning on every method call.

methodName : function() {
  qx.log.Logger.deprecatedMethodWarning(
    arguments.callee, "Message... a hint to the alternative method ..."
  );
  // old code or delegate to the new method
}  

If you change the amount of arguments, you have to check the number of arguments supplied and throw a deprecation warning if the right number of arguments was not given.

if (arguments.length !==1) {  // test for one argument here
  qx.log.Logger.deprecatedMethodWarning(
    arguments.callee, "Message... a hint to the new usage of the method..."
  );
}

The same should be done if the type of an argument changes. If the old type is supplied, a warning should be thrown as in the example above.

Problematic.

• Copy and rename the original method to "originalName_deprecated", and mark it as deprecated.
• Rewrite the original method to return the new type.
• …

Events should be declared as deprecated in the comment section of the event. This works exactly like the deprecation of methods:

/**
 * ...
 * @deprecated
 */

This will force the generated API to include a deprecation note. Additionally you should throw a warning at runtime similar to deprecated methods. But you need to throw a warning if someone registers for that event. To do that, you can override the addListener() function in your current class.

// overridden
addListener: function(type, listener, self, capture) {
  if (type == "eventName") {
    qx.log.Logger.deprecatedEventWarning(
      arguments.callee, 
      "eventName",
      "Deprecation message..."
    );        
  }
 
  return this.base(arguments, type, listener, self, capture);
}

But be careful if you reintroduce the event in a subclass of your current class. The warning will also be fired for all subclasses. If you have such a use case, include an additional check for the classname to limit the warning to the current class.

Not possible to deprecate reliably?

Properties are used throughout the framework. Because their accessor and mutator methods will be auto-generated at runtime, deprecating properties is problematic.

Removing a property is a complex task. You have to replace all the generated methods with handwritten methods and throw deprecation warnings on every call (see the deprecation of methods section for details). Remember to implement the checks and the storage of the properly too. The amount of methods depends on the configuration of the property. The default methods are:

• setPropertyName()
• getPropertyName()
• resetPropertyName()
• initPropertyName()

If the value is of Boolean value, two additional methods are generated by the property system and should be implemented as well:

• isPropertyName()
• togglePropertyName()

If the property has a change event defined, add the event to the events section in the class map and deprecate it as described in the events section. But keep in mind that you have to fire the event manually in the handwritten setter. If you have to remove the same property at various places, you can add all deprecation methods to a mixin and include that mixin in all classes which have the old property.

Renaming a property is the same as removing a property and introducing a new property. But you can delegate the handwritten accessors of the old property to the new accessors.

Changing the check of a property causes the most problems. You have to write a manual check function to allow the old and the new type to be set. This could look like the following code.

propertyName :
{
  check : "return qx.lang.Type.isString(value) || qx.lang.Type.isBoolean(value)"
}

This check allows string as well as Boolean values to be set. But be careful with that. Remember you have to implement the additional boolean accessors isPropertyName() and togglePropertyName(). What applies to methods and events also applies to properties. You can not return both a string and a Boolean value, nor can you set both types in the data event.