Gecko:Obsolete API

APIs that are declared as obsolete, by virtue of being on this list have their days numbered in the codebase. They will be removed at some point in the future. Because of this, no new code is allowed to use any of the classes, functions, or types that appear on this list, except if they must conform to an older interface that demands the usage of an obsolete type. Reviewers and superreviewers should become familiar with this list for this reason.

If at all possible, please provide a) a suggested alternate class or function that provides similar functionality; and b) a link to a bug for removing the obsolete API from the codebase. The bug should contain rationale for obsoleting that API. To propose an API for obsolescence, please file a bug and add it to the proposed obsolete API section.

Obsolete API

• nsIFileSpec, nsFileSpec
  • FileSpec has various issues, including being limited to the system character set for filenames.
  • Use nsIFile/nsILocalFile/nsILocalFile{In,Out}putStream
  • https://bugzilla.mozilla.org/show_bug.cgi?id=38122
• nsIPref
  • Use nsIPrefService/nsIPrefBranch/nsIPrefBranch2
  • https://bugzilla.mozilla.org/show_bug.cgi?id=175193
• ns(I)SupportsArray, nsIEnumerator
  • nsSupportsArray is very inefficient and has a bad API
  • Use any of the arrays in The Mozilla Array Guide.
• nsVoidArray
  • Doesn't provide typesafety
  • Prefer to use nsTArray or nsCOMArray.
• nsAutoVoidArray
  • Use nsAutoTArray
• nsAutoBuffer
  • Use nsAutoTArray
• nsStringArray, nsCStringArray
  • Malloc-happy
  • Use nsTArray<nsC?String> if possible.
• nsHashtable
  • Non-typesafe wrapper around pldhash.
  • Use one of the hashtables in The Mozilla Hashtable Guide
• nsIBox
  • This is now just a typedef for nsIFrame.
• nsIDOMEventReceiver, and all specialized DOM event listener interfaces (better to use nsIDOMEventListener), e.g:
  • nsIDOMCompositionListener
  • nsIDOMContextMenuListener
  • nsIDOMDragListener
  • nsIDOMFocusListener
  • nsIDOMFormListener
  • nsIDOMKeyListener
  • nsIDOMLoadListener
  • nsIDOMMouseListener
  • nsIDOMMouseMotionListener
  • nsIDOMMutationListener (unused, remove in 1.9?, https://bugzilla.mozilla.org/show_bug.cgi?id=360847)
  • nsIDOMPageTransitionListener (unused, remove in 1.9?, https://bugzilla.mozilla.org/show_bug.cgi?id=360847)
  • nsIDOMPaintListener (unused, remove in 1.9?, https://bugzilla.mozilla.org/show_bug.cgi?id=360847)
  • nsIDOMScrollListener (unused, remove in 1.9?, https://bugzilla.mozilla.org/show_bug.cgi?id=360847)
  • nsIDOMTextListener
  • nsIDOMUIListener
  • nsIDOMXULListener

Proposed Obsolete API

• NS_GET_IID, NS_DEFINE_IID, and T::GetIID, except when NS_GET_IID is used on a template parameter.
  • Instead, use function templates (like CallQueryInterface) or nsCOMPtr_helpers (like do_QueryInterface) to tie the XPCOM and C++ type systems together rather than casting between the two type systems.
• nsA[C]String
  • use ns[C]Substring when nsA[C]String is not required by existing APIs (although it is still required by XPCOM interfaces)
• NS_NewAtom, NS_NewPermanentAtom
  • use do_GetAtom, do_GetPermanentAtom instead
• nsIRenderingContext, nsIDrawingSurface, nsIFontMetrics, nsTransform2D, nsFont, etc
  • any substantial new rendering code should be written to Thebes directly; that is, gfxContext, gfx*Surface, gfxPlatform, gfxFontGroup, gfxTextRun.