Skip to main content
Engineering LibreTexts

7.11: Deprecate Obsolete Interfaces

  • Page ID
    32911
  • \( \newcommand{\vecs}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} } \) \( \newcommand{\vecd}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash {#1}}} \)\(\newcommand{\id}{\mathrm{id}}\) \( \newcommand{\Span}{\mathrm{span}}\) \( \newcommand{\kernel}{\mathrm{null}\,}\) \( \newcommand{\range}{\mathrm{range}\,}\) \( \newcommand{\RealPart}{\mathrm{Re}}\) \( \newcommand{\ImaginaryPart}{\mathrm{Im}}\) \( \newcommand{\Argument}{\mathrm{Arg}}\) \( \newcommand{\norm}[1]{\| #1 \|}\) \( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\) \( \newcommand{\Span}{\mathrm{span}}\) \(\newcommand{\id}{\mathrm{id}}\) \( \newcommand{\Span}{\mathrm{span}}\) \( \newcommand{\kernel}{\mathrm{null}\,}\) \( \newcommand{\range}{\mathrm{range}\,}\) \( \newcommand{\RealPart}{\mathrm{Re}}\) \( \newcommand{\ImaginaryPart}{\mathrm{Im}}\) \( \newcommand{\Argument}{\mathrm{Arg}}\) \( \newcommand{\norm}[1]{\| #1 \|}\) \( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\) \( \newcommand{\Span}{\mathrm{span}}\)\(\newcommand{\AA}{\unicode[.8,0]{x212B}}\)

    Also Known As: Deprecation [SP98].

    Intent Give clients time to react to changes to public interfaces by flagging obsolete interfaces as “deprecated”.

    Problem

    How do you modify an interface without invalidating all the clients?

    This problem is difficult because:

    • Changing a public interface can break many clients.

    • Leaving an obsolete interface in place will make future maintenance more difficult.

    • Not all changes are for the better.

    Yet, solving this problem is feasible because:

    • The old and the new interfaces can coexist for a period of time.

    Solution

    Flag the old interface as being “deprecated”, thereby notifying clients that it will almost certainly be removed in the next upcoming release.

    Steps

    • You have determined that a public interface should be changed, but you do not want to break all clients. Implement the new interface, but “deprecate” the old one. The deprecation mechanism should inform clients that the interface has changed, and that a newer interface is recommended instead.

    • Evaluate to what extent the deprecated interface continues to be used, and whether it can be permanently retired. Consider removing it in a future release.

    • Java supports deprecation as a language feature:

      • Deprecate a feature by adding the tag @deprecated to its javadoc documentation. The tag is not only recognized by the javadoc documentation generator, but the compiler will also generate compile-time warnings if code using deprecated features is compiled with the -deprecated option.

    • Other approaches are:

      • Simply inform users in the documentation which interfaces are deprecated.

      • Move or rename the deprecated interface or component. Clients can continue to use them, but must adapt and recompile to continue to use the deprecated form.

      • Replace deprecated components by equivalent ones that generate run-time warnings or output warnings to a log file.

      • Alternatively, consider configuring the programming environment or the deprecated components themselves to generate compile-time or link-time warnings.

    Tradeoffs

    Pros

    • Clients do not have to immediately adapt to changes.

    • There is time to change your mind.

    Cons

    • Clients are free to ignore deprecation.

    Difficulties

    • It may be hard to track down all the clients of a deprecated component.

    • It can be hard to decide when to really retire a deprecated component.

    • If you want to keep the interface but change the semantics, you may need to introduce a new component and deprecate the old one. This can be the case if certain methods should now return default values instead of throwing exceptions (or vice versa).

    Known Uses

    Perdita Stevens and Rob Pooley identify Deprecation as a common practice for managing evolving APIs in complex systems [SP98].

    Rationale

    Deprecation gives you a window of time to evaluate the impact of a change.


    This page titled 7.11: Deprecate Obsolete Interfaces is shared under a CC BY-SA license and was authored, remixed, and/or curated by Serge Demeyer, Stéphane Ducasse, Oscar Nierstrasz.

    • Was this article helpful?