MozillaZine

Implementing XPCOM components in JavaScript

From MozillaZine Knowledge Base

(Difference between revisions)
Revision as of 19:05, 24 February 2006
Dietrich (Talk | contribs)
(Accessing your Class)
<-- Previous diff
Revision as of 00:19, 4 March 2006
Asqueella (Talk | contribs)
(other resources)
Next diff -->
Line 1: Line 1:
{{extdev}} {{extdev}}
- 
==About XPCOM== ==About XPCOM==
Line 142: Line 141:
</pre> </pre>
 +
 +== Other resources ==
 +* Two mozillazine forums threads about implementing XPCOM components in JS with some explanations, example code, and troubleshooting tips:
 +** http://forums.mozillazine.org/viewtopic.php?t=308369
 +** http://forums.mozillazine.org/viewtopic.php?t=367298
 +* [http://developer.mozilla.org/en/docs/How_to_Build_an_XPCOM_Component_in_Javascript How to Build an XPCOM Component in Javascript] at developer.mozilla.org

Revision as of 00:19, 4 March 2006

This page is part of the extension development documentation project.

Ask your questions in MozillaZine Forums. Also try browsing example code.

Note: development documentation is in process of being moved to Mozilla Development Center (MDC).

Contents

About XPCOM

Mozilla applications are built from a collection of XPCOM (Cross-platform Component Object Model) classes. They are used to perform certain tasks or to get specific functionality. For example, there is a directory service class that can be used to access files on your file system. Classes can be constructed using several programming languages, including: javascript, c++, and python. Mozilla then uses "interfaces" to describe what a class can do. The most basic interface nsISupports is used to retrieve the different interfaces that a class implements.

Benefits of XPCOM

  • XPCOM classes can be used by any programming language mozilla supports.
  • Objects implemented as XPCOM are global to an application, and are not dependent on the scope of any one window.
  • Programming logic can be encapsulated within a class.

XPCOM Drawbacks

  • Objects must be accessed from their defined interfaces. Javascript shortcuts such as the global window object cannot be accessed.
    • The only exception to this rules, is if you set a magical property wrappedJSObject equal to your class, then the underlining javascript object can be accessed.
  • It is easier to have memory leaks. This article on the Mozilla.org website provides an explanation of how and why this can occur, and tips on avoiding leakage in Javascript.

XPCOM Concepts

There are basically 4 concepts you need to understand when developing XPCOM objects. They are classes, interfaces, modules, and factories. I will give a brief summary of each, then go into more details later.

Classes

A class is simply an XPCOM object that implements interfaces, and is registered with the component manager. In our case we are going to implement a Javascript object which will be our class.

Interfaces

Interfaces are used to define what functions and attributes an xpcom class provides. nsISupports is an interface that all classes must implement. It provides a function to request the interfaces on a class.

Factories

Factories are objects used to instantiate classes. it implements the nsIFactory interface.

Modules

Multiple classes can be defined in a file. A module is an object that is used to register, unregister and provide factories for classes. It implement the nsIModule interface.

Getting Started

For our example, we are going to create a file that contains one class, one module, and one factory. The class will implement the required nsISupports interface, and the nsISupportsPriority interface. A simple example of an actual Mozilla component is the nsDictionary class. A complex example that implements multiple classes is the nsUpdateService.

Note: This example implements pre-existing interfaces, and therefore does not address the creation or compilation of interface descriptions (IDL) for our component. A more comprehensive tutorial that covers creating an XPCOM in Javascript from scratch can be found here.

How it Works

Startup and Registration

During the startup process if the file compreg.dat is missing or the file .autoreg exists, the application knows that it needs to register components. It then loads files from each of the components folders, including the components folder in each extension directory. It then calls the function NSGetModule on each file to get the object that implements the nsIModule interface.

//module initialization
function NSGetModule(aCompMgr, aFileSpec) { return MyPriorityModule; }


Accessing your Class

// instanciate component object
var oMyPriority = Components.classes['@mozillazine.org/example/priority;1'].
                             createInstance(Components.interfaces.nsISupportsPriority);

// lower priority
oMyPriority.adjustPriority(10);

Finished Code

Below is how the finished code may look.


// constants
const nsISupportsPriority = Components.interfaces.nsISupportsPriority;
const nsISupports = Components.interfaces.nsISupports;
const CLASS_ID = Components.ID("{1C0E8D86-B661-40d0-AE3D-CA012FADF170}");
const CLASS_NAME = "My Supports Priority Component";
const CONTRACT_ID = "@mozillazine.org/example/priority;1";

//class constructor
function MyPriority() {
  this._priority = nsISupportsPriority.PRIORITY_LOWEST;
};

//class definition
MyPriority.prototype = {
  _priority: null,

  get priority() { return this._priority; },
  set priority(aValue) { this._priority = aValue; },

  adjustPriority: function(aDelta) {
    this._priority += aDelta;
  },

  QueryInterface: function(aIID)
  {
    if (!aIID.equals(nsISupportsPriority) &&    
        !aIID.equals(nsISupports))
      throw Components.results.NS_ERROR_NO_INTERFACE;
    return this;
  }
};

//class factory
var MyPriorityFactory = {
  createInstance: function (aOuter, aIID)
  {
    if (aOuter != null)
      throw Components.results.NS_ERROR_NO_AGGREGATION;
    return (new MyPriority()).QueryInterface(aIID);
  }
};

//module definition (xpcom registration)
var MyPriorityModule = {
  _firstTime: true,
  registerSelf: function(aCompMgr, aFileSpec, aLocation, aType)
  {
    if (this._firstTime) {
      this._firstTime = false;
      throw Components.results.NS_ERROR_FACTORY_REGISTER_AGAIN;
    };
    aCompMgr = aCompMgr.QueryInterface(Components.interfaces.nsIComponentRegistrar);
    aCompMgr.registerFactoryLocation(CLASS_ID, CLASS_NAME, CONTRACT_ID, aFileSpec, aLocation, aType);
  },

  unregisterSelf: function(aCompMgr, aLocation, aType)
  {
    aCompMgr = aCompMgr.QueryInterface(Components.interfaces.nsIComponentRegistrar);
    aCompMgr.unregisterFactoryLocation(CLASS_ID, aLocation);        
  },
  
  getClassObject: function(aCompMgr, aCID, aIID)
  {
    if (!aIID.equals(Components.interfaces.nsIFactory))
      throw Components.results.NS_ERROR_NOT_IMPLEMENTED;

    if (aCID.equals(CLASS_ID))
      return MyPriorityFactory;

    throw Components.results.NS_ERROR_NO_INTERFACE;
  },

  canUnload: function(aCompMgr) { return true; }
};

//module initialization
function NSGetModule(aCompMgr, aFileSpec) { return MyPriorityModule; }

Other resources