Component is an abstract class that serves as basis for defining replaceable software modules that extend the basic map with additional functionality. Components allow API users to:

• include new functionality
• replace existing functionality with a different implementation
• deactivate existing functionality.

A component may fire custom events.

The Component class is implemented in several packages outside the map package, for example in routing and search.

Reference counting

The fact that components are replaceable and that they can add or remove other components, creating and potentially disrupting inter-component dependencies, makes a reference counting mechanism necessary. The basic principle is that whenever a component is created its reference count is incremented to indicate that the creator requires it (and holds a reference to it). The count is also incremented when a component already exists, but a new attempt to create it is made - thus, the count goes up, but duplicate components with the same id are not created. An attempt to deleted/remove a component, causes its reference count to be decremented.

This mechanism prevents not only component duplication, but also the removal of components while other components dependent on them for as long as the dependencies exist. Caution when physically removing components is necessary, because on removal, a component's detach callback is called to delete its reference to the map Display. As a result, the component becomes unusable in an invalid state.

However, this mechanism remains transparent and you, as the API user simply need to call the methods addComponent() and removeComponent of the map Display class to add and remove components, respectively. Here is an example:

// If a Kinetic component already exists, addComponent()   
// returns it instead of creating a duplicate.
var component = display.addComponent(new nokia.maps.map.component.panning.Kinetic());

// If any other component or application part holds a reference 
// to the component, this call does not remove the component, but 
// decrements the reference counter by one, otherwise it removes
// the component (if the reference counter reached zero).
display.removeComponent(component);

// Another possibility to remove a component is:
display.removeComponent( display.getComponentById("panning.Kinetic") );