Dictionary

Die "Dictionary"-Klasse stellt unter JavaScript eine Tabelle mit literal indizierten Elementen zur Verfügung. Zwar verfügen auch "normale" JavaScript-Objekte bereits über diese Eigenschaft, allerdings teilen sich dort die eigentlichen Tabellen-Elemente ihren Namensraum mit den Methoden und Datenfeldern des Tabellen-Objektes, so daß "unglücklich" gewählte Indizes das Verhalten dieses Objektes beeinflussen können - im Gegensatz dazu sind in einem "Dictionary" die Elemente strikt von den eigenen Datenfeldern und Methoden getrennt (und tauchen insbesondere auch nicht in einer for-in-Schleife auf). Die Programmierschnittstelle ist in etwa eine Mischung aus der des von Microsoft's JScript bereitgestellten Datentyps "Dictionary" sowie der Java-Klasse java.util.Dictionary.

Aufgrund der Erfahrungen mit der "Enumerator"-Implementierung wurde die "Dictionary"-Klasse als Rhino "Host Object" realisiert. Eine zusätzliche, explizit implementierte Methode der "Scriptable"-Schnittstelle regelt die Sichtbarkeit von Methoden und Datenfeldern.

Objektbeschreibung (JavaScript)

Konstruktor

new Dictionary ()

erzeugt ein neues, leeres "Dictionary"-Objekt;

Datenfelder

Count

enthält die Anzahl der im "Dictionary" abgelegten Elemente (read-only);

Items

enthält eine Aufzählung aller im "Dictionary" abgelegten Elemente (ohne die zugehörigen Schlüssel). Die Reihenfolge der Elemente in dieser Aufzählung ist nicht festgelegt (read-only);

Keys

enthält eine Aufzählung der Schlüssel aller im "Dictionary" abgelegten Elemente (ohne die Elemente selbst). Die Reihenfolge der Schlüssel in dieser Aufzählung ist nicht festgelegt (read-only);

Methoden

add (Key, Item)

trägt ein Item unter dem angegebenen Schlüssel (Key) in das "Dictionary" ein. Ein unter diesem Schlüssel evtl. bereits eingetragenes Element wird dabei überschrieben;

equals (Object) -> Boolean

prüft, ob das "Dictionary"-Objekt mit dem angegebenen Objekt identisch ist bzw. diesem inhaltlich gleicht - falls ja, liefert die Funktion den Wert true zurück, ansonsten ist das Ergebnis false;

get (Key) -> Object

liefert das unter dem angegebenen Schlüssel (Key) im "Dictionary" abgelegte Objekt - oder undefined, falls ein solcher Schlüssel nicht existiert (get- und Item-Methode sind äquivalent);

has (Key) -> Boolean

prüft, ob unter dem angegebenen Schlüssel (Key) im "Dictionary" ein Objekt abgelegt ist - falls ja, liefert die Funktion den Wert true zurück, ansonsten ist das Ergebnis false;

isEmpty () -> Boolean

prüft, ob das "Dictionary" leer ist, d.h. keine Elemente enthält - falls ja, liefert die Funktion den Wert true zurück, ansonsten ist das Ergebnis false;

Item (Key) -> Object

liefert das unter dem angegebenen Schlüssel (Key) im "Dictionary" abgelegte Objekt - oder undefined, falls ein solcher Schlüssel nicht existiert (get- und Item-Methode sind äquivalent);

Key (Key) -> Object

prüft, ob unter dem angegebenen Schlüssel (Key) im "Dictionary" ein Objekt abgelegt ist - falls ja, liefert die Funktion den Schlüssel unverändert zurück, ansonsten ist das Ergebnis undefined;

put (Key, Item) -> Object

trägt ein Item unter dem angegebenen Schlüssel (Key) in das "Dictionary" ein und liefert das zuvor unter diesem Schlüssel eingetragene (und bei dem Vorgang überschriebene) Element zurück. Falls kein solches Element existiert, ist das Ergebnis der Methode undefined;

remove (Key) -> Object

löscht ein unter dem angegebenen Schlüssel (Key) abgelegtes Objekt aus dem "Dictionary" und liefert es als Methoden-Ergebnis zurück - falls kein solches Element existiert, ist das Ergebnis der Methode undefined;

removeAll ()

löscht alle eingetragenen Objekte aus dem "Dictionary";

toString () -> String

liefert eine literale Repräsentaton des "Dictionary"-Objektes;

Verwendungshinweise (JavaScript)

Erzeugen und Bearbeiten eines neuen Dictionary

Die Verwendung von "Dictionary"-Objekten ist denkbar einfach: zunächst wird ein leeres "Dictionary" angelegt:

  var Table = new Dictionary();

Dieses kann nun - z.B. im Rahmen einer Schleife - mit Einträgen gefüllt werden:

  Table.add("anyKey",anyObject);
  ... = Table.put("anotherKey",anotherObject);

Der Unterschied zwischen add und put besteht darin, daß put das zuvor unter dem angegebenen Schlüssel gespeicherte Objekt zurückliefert - falls das "Dictionary" bislang kein derartiges Element enthält, liefert put den Wert undefined.

Mithilfe von has kann die Existenz eines Schlüssels in einem "Dictionary" überprüft werden:

  if (Table.has("anyKey")) {...};

Und mittels get oder Item wird gezielt auf einen gewünschten Eintrag zugegriffen:

  ... = Table.get("anyKey");
  ... = Table.Item("anotherKey");

Beide Methoden sind zueinander äquivalent.

Bearbeitung aller Elemente eines Dictionary

Mithilfe einer Aufzählung können nacheinander alle in ein "Dictionary" eingetragenen Schlüssel oder Elemente bearbeitet werden:
 

  var KeyList = Table.Keys;
  for (; !KeyList.atEnd(); KeyList.moveNext()) {
    passende Bearbeitung von KeyList.actualElement bzw. Table.Item(KeyList.actualElement)
  };

  var ItemList = Table.Items;
  for (; !ItemList.atEnd(); ItemList.moveNext()) {
    passende Bearbeitung von ItemList.actualElement
  };

In der ersten Schleife werden nacheinander alle Schlüssel eines "Dictionary" bearbeitet - dies dürfte der gebräuchlichere Anwendungsfall sein. Die zweite Schleife behandelt dagegen alle in ein "Dictionary" eingetragenen Objekte. Nota bene: Objekte, die mehrmals (unter unterschiedlichen Schlüsseln) in das "Dictionary" eingetragen wurden, tauchen auch entsprechend häufig in der Items-Aufzählung auf - ein Schlüssel kann hingegen immer nur einmal auftreten.

Löschen von Einträgen aus einem Dictionary

Mithilfe von remove kann ein Eintrag aus einem "Dictionary" entfernt werden:

  ... = Table.remove("anyKey");

Das ausgetragene Objekt wird dabei als Methoden-Ergebnis zurückgeliefert - falls der zu löschende Eintrag gar nicht existiert, ist das Ergebnis der Methode undefined.

Die Methode removeAll löscht alle Einträge aus einem "Dictionary":

  Table.removeAll();

Anwendungsbeispiel (JavaScript)

Das Rhino-Skript DictionaryTest.js verdeutlicht das Anlegen eines "Dictionary" sowie dessen Verwendung. Zusätzlich werden alle Slots des "Dictionary"-Objektes angezeigt.

Das Programm wird ohne Angabe von Kommandozeilen-Argumenten aufgerufen

  java Rhino DictionaryTest.js

und liefert folgende Ausgabe:

  DictionaryTest - tests the "sunda.rhino.data.Dictionary" class

  constructing a dictionary...
  printing the dictionary's contents:
   - "String" = anything
   - "Number" = 2
   - "Boolean" = true

  printing the dictionary itself:
    {String=anything, Number=2, Boolean=true}

  constructing another dictionary with the same content...
    Table == equalTable?     true

  constructing another dictionary with different content...
    Table == differentTable? false

  examining the dictionary's properties:
   - add: function add() {        [native code] }
   - Count: 3
   - equals: function equals() {  [native code] }
   - get: function get() {        [native code] }
   - has: function has() {        [native code] }
   - isEmpty: function isEmpty() {        [native code] }
   - Item: function Item() {      [native code] }
   - Items: (anything,2,true)
   - Key: function Key() {        [native code] }
   - Keys: (String,Number,Boolean)
   - put: function put() {        [native code] }
   - remove: function remove() {  [native code] }
   - removeAll: function removeAll() {    [native code] }
   - toString: function toString() {      [native code] }

Wie aus der Programmausgabe ersichtlich, verhält sich die "Dictionary"-Implementierung beinahe wie eine intrinsische Rhino-Klasse und bedarf deshalb keiner weiteren Erläuterung.

Quelltexte

Alle Java-Klassen und Rhino-Skripte sind auch im Quelltext verfügbar:

• Dictionary.java
• DictionaryTest.js

Literaturhinweise

Netscape
Tutorial: Embedding Rhino
(siehe http://www.mozilla.org/rhino/tutorial.html)
die angegebene Anleitung beschreibt Verfahren zur Verknüpfung von Java und JavaScript (Rhino);

Sun Microsystems, Inc.
java.util Interface Dictonary
(siehe http://java.sun.com/j2se/1.4/docs/api/java/util/Dictionary.html)
hinter der angegebenen URL verbirgt sich die im Netz verfügbare Beschreibung der (inzwischen veralteten) Java-Klasse java.util.Dictionary;

Microsoft
JScript Documentation
(siehe http://msdn.microsoft.com/library/default.asp/?url=/library/en-us/script56/html/js56jsoriJScript.asp)
die Dokumentation zu Microsoft's JScript enthält nicht nur ein sehr schönes JScript-Tutorial, sondern beschreibt auch die Microsoft-spezifischen Erweiterungen des JavaScript-Standards (u.a. auch den Dictionary-Datentyp);