Entsprechung zwischen JSON-Zeichenfolge und EGL-Variable

In diesem Abschnitt wird der EGL-Datensatz beschrieben, der einer JavaScript Object Notation-Zeichenfolge (JSON) entspricht. Weitere Abschnitte beschreiben die Funktionen serviceLib.convertFromJSON() und serviceLib.convertToJSON(), die von Rich UI-Entwicklern verwendet werden, um JSON-Daten in eine Variable oder aus einer Variablen zu konvertieren, was unter Umständen erforderlich ist, um auf einen REST-Service anderer Anbieter zugreifen zu können. Bei Fehlschlagen einer dieser Funktionen wird eine Laufzeitausnahmebedingung (RuntimeException) ausgelöst.

JSON- und EGL-Zeichenfolgen

Sie können einen Datensatz definieren, um auf eine JSON-Zeichenfolge wie in diesem Beispiel zuzugreifen:
{ "EmpNo":10,"LastName":"Smith" }  
Innerhalb der Klammern einer JSON-Zeichenfolge stellt jedes Paar aus Kennung und Wert (wie beispielsweise "Empno":10) den Namen und den Wert eines JSON-Felds dar. Um einen Datensatzabschnitt (Record) zu erstellen, der der JSON-Zeichenfolge entspricht, müssen Sie sicherstellen, dass jeder Feldname im Datensatzabschnitt (nach Zeichen und Groß-/Kleinschreibung) genau dem zugehörigen Feldnamen in der JSON-Zeichenfolge entspricht, wie im folgenden Beispiel gezeigt wird:
Record MyRecordPart
   EmpNo INT;
   LastName STRING;
end

Sie können jeden Basiselementtyp mit Ausnahme von BLOB und CLOB verwenden. Ein EGL-Datensatzfeld ist auch gültig, wenn es auf einem Datenelementabschnitt (DataItem) basiert, der wiederum auf einem der unterstützten Basiselementtypen basiert.

Die EGL-Eigenschaft 'JSONName' ermöglicht es Ihnen, eine JSON-Zeichenfolge zu verwenden, in der ein Feldname ein für EGL reserviertes Wort ist oder in EGL nicht gültig ist. Im Folgenden sehen Sie eine Variante der JSON-Beispielzeichenfolge:
{ "Emp-No":10,"LastName":"Smith" }  
In diesem Fall besteht das Problem darin, dass Sie in einem EGL-Datensatz keinen Feldnamen erstellen können, der einen Bindestrich enthält. Sie können jedoch die Eigenschaft 'JSONName' verwenden, um den JSON-Feldnamen im Datensatzabschnitt beizubehalten, wie im Folgenden gezeigt wird:
Record MyRecordPart
   EmpNo INT; {JSONName = "Emp-No"}
   LastName STRING;
end

(Sie können den Wert von 'JSONName' nicht überschreiben, wenn Sie einen Datensatz deklarieren, der auf dem Datensatzabschnitt basiert.)

In vielen Fällen enthält der Datensatz für den Zugriff auf eine JSON-Zeichenfolge ebenfalls Datensätze. Wenn Sie jedoch Datensätze verwenden und die Funktion 'serviceLib.convertFromJSON()' oder 'serviceLib.convertToJSON()' aufrufen, referenzieren Sie lediglich einen einzelnen Datensatz, der auf dem Datensatzabschnitt basiert, der von sämtlichen erforderlichen Datensatzabschnitten auf der höchsten Ebene liegt (und den meisten Inhalt umfasst). So könnte beispielsweise die folgende JSON-Zeichenfolge zurückgegeben werden, wenn ein Service für Zeitabruf (getTime) verwendet wird, der die Anzahl der Sekunden seit 01. Januar 1970 berechnet:
{"Result":{"aTimestamp":1191871152}}

Als allgemeine Regel gilt, dass jede in Klammern eingeschlossene Klausel in einer JSON-Zeichenfolge der Inhalt eines JSON-Laufzeitobjekts ist, das zu einem EGL-Datensatz äquivalent ist.

Im aktuellen Beispiel müssen zwei Datensatzabschnitte definiert werden. Der Datensatz zur Verwendung in 'serviceLib.convertFromJSON()' oder 'serviceLib.convertToJSON()' basiert auf dem folgenden Abschnitt, der ein Ergebnisfeld 'Result' enthält:
Record MyTopPart
   Result MyTimestampPart;
end
Entsprechend der Struktur der JSON-Zeichenfolge besitzt der nächste Datensatzabschnitt ein Feld namens aTimestamp:
Record MyTimestampPart
   aTimestamp BIGINT;
end

Wie gezeigt muss für jede JSON-Kennung (die vor einem Doppelpunkt steht) ein Feld in einem Datensatz vorhanden sein. Wenn ein JSON-Feldname ein für EGL reserviertes Wort ist (beispielsweise "TimeStamp"), müssen Sie auf 'serviceLib.convertFromJSON()' oder 'serviceLib.convertToJSON()' zugreifen, indem Sie ein Wörterverzeichnis Dictionary) anstelle eines Datensatzes verwenden. Diese Variante wird weiter unten in diesem Thema gezeigt.

Es folgt ein weiteres Beispiel, das zwar für bessere Lesbarkeit erneut formatiert wurde, jedoch von http://json.org/ stammt - einer Website, auf der JSON im Detail beschrieben wird:
{"Menu": 
  { "id": "file", "value": "File", "popup": 
     {"Menuitem": 
       [
         {"value": "New", "onClick": "CreateNewDoc()"},
         {"value": "Open", "onClick": "OpenDoc()"},
         {"value": "Close", "onClick": "CloseDoc()"}
       ]   
     }
  }
}

(Als das vorliegende Thema geschrieben wurde, befand sich das betreffende Beispiel zusammen mit anderen unter http://json.org/example.html.)

Der auf der höchsten Ebene liegende (und den meisten Inhalt umfassende) Datensatzabschnitt enthält ein Feld namens Menu:
Record MyTopPart
   Menu MyMenuPart;
end
Um die anderen Datensatzabschnitte zu erstellen, wird jede in Klammern eingeschlossene Klausel in der JSON-Zeichenfolge berücksichtigt. Der nächste Datensatzabschnitt (MyMenuPart) enthält die Felder id, value und popup:
Record MyMenuPart
   id STRING; 
   value STRING;
   popup MyPopupPart;
end
Der nächste Datensatzabschnitt enthält eine Feldgruppe namens MenuItem:
Record MyPopupPart
   MenuItem MyElementPart[];
end
Der letzte Datensatzabschnitt enthält die Felder value und onClick:
Record MyElementPart
   value STRING; 
   onClick STRING;
end

Um mehr darüber zu erfahren, wie ein Datensatz beim Zugriff auf eine JSON-Zeichenfolge verwendet wird, lesen Sie die Informationen im Rich UI-Beispiel 'geocode.records'.

JSON- und EGL-Wörterverzeichnisse

Ein EGL-Wörterverzeichnis (Dictionary) enthält eine Gruppe von Einträgen, die jeweils einen Schlüssel und einen Wert eines beliebigen Typs enthalten, wie in der folgenden Variablendeklaration:
myRef Dictionary 
{ 
   ID = 5,
   lastName = "Twain",
   firstName = "Mark"
};

Eine Beschreibung der Interaktion mit dem Wörterverzeichnis finden Sie unter 'Wörterverzeichnisabschnitt' und in den einschlägigen Themen im EGL-Hilfesystem.

Es könnte die folgende JSON-Zeichenfolge zurückgegeben werden, wenn ein Service für Zeitabruf (getTime) verwendet wird, der die Anzahl der Sekunden seit 01. Januar 1970 berechnet:
{"Result":{"aTimestamp":1191871152}}
Sie haben die Möglichkeit, die JSON-Zeichenfolge (von der Klammer ganz links bis zur Klammer ganz rechts) in ein Wörterverzeichnis namens 'myTime' umzusetzen, das ohne Details deklariert wird:
myTime Dictionary;

Als allgemeine Regel gilt, dass jede in Klammern eingeschlossene Klausel in einer JSON-Zeichenfolge zu einem EGL-Wörterverzeichnis äquivalent ist. Im Zusammenhang mit der JSON-Beispielzeichenfolge behandelt die Funktion 'serviceLib.convertFromJSON()' das Symbol links vom ersten Doppelpunkt (:) als Schlüssel eines Wörterverzeichniseintrags. Der Schlüssel heißt 'Result' (Ergebnis) und ist von der Groß-/Kleinschreibung abhängig. Hierbei (wie in allen Fällen) ist der Inhalt rechts von einem Doppelpunkt der Wert, der dem Schlüssel zugeordnet ist, dessen Name sich links vom betreffenden Doppelpunkt befindet.

Die eingebetteten Klammern zeigen an, dass es sich bei dem Wert von 'Result' um ein anonymes Wörterverzeichnis handelt. Wie zuvor trennt der Doppelpunkt innerhalb dieser Klammern einen Schlüssel (aTimestamp) von einem Wert (1191871152). Die Ausgabe der Funktion 'serviceLib.convertFromJSON()' kann also wie folgt verstanden werden:
myTime Dictionary 
{ 
   Result = new Dictionary{ aTimestamp = 1191871152 }
};   
Sie können mithilfe der Punktsyntax wie folgt auf den Inhalt von 'aTimestamp' zugreifen:
numberOfSeconds BIGINT = myTime.Result.aTimestamp;
In bestimmten Fällen ist die Punktsyntax nicht gültig. Der Service 'getTime' von Yahoo beispielsweise gibt den folgenden Inhalt, einschließlich des für EGL reservierten Worts Timestamp, zurück:
{"Result":{"Timestamp":1191871152}}
Um auf einen Wert zuzugreifen, dessen Schlüssel ein für EGL reserviertes Wort ist, müssen Sie die Klammersyntax verwenden. Der folgende EGL-Code ist für die Daten gültig, die vom Service 'getTime' von Yahoo zurückgegeben werden:
numberOfSeconds BIGINT = myTime.Result["Timestamp"];
Es folgt noch einmal das Beispiel 'Menu' von http://json.org/:
{"Menu": 
  { "id": "file", "value": "File", "popup": 
     {"Menuitem": 
       [
         {"value": "New", "onClick": "CreateNewDoc()"},
         {"value": "Open", "onClick": "OpenDoc()"},
         {"value": "Close", "onClick": "CloseDoc()"}
       ]   
     }
  }
}

In diesem Beispiel, hat das Wörterverzeichnis einen einzelnen Eintrag, dessen Schlüssel den Namen 'Menu' besitzt. Der Wert, der diesem Schlüssel zugeordnet ist, ist ein anonymes Wörterverzeichnis, was aus den Klammern hervorgeht, die die Zeichenfolge "id" und alle folgenden Zeichenfolgen einbetten. Dieses anonyme Wörterverzeichnis enthält die Schlüssel id, value und popup mit den zugehörigen Werten. Möglicherweise tritt bei Ihnen niemals die Komplexität auf, die der Schlüssel namens popup bedeutet, aber das Problem ist lösbar. Die Beziehungen werden aus der JSON-Beispielzeichenfolge ersichtlich.

Folgende Fragestellung sollte berücksichtigt werden: Welche Anweisung ist erforderlich, um auf die Zeichenfolge "OpenDoc()" zuzugreifen, unter der Annahme, dass die Funktion 'serviceLib.convertFromJSON()' die vorherige JSON-Zeichenfolge in ein Verzeichnis namens 'myMenu' kopiert hat?

Die Antwort lautet wie folgt:
myString STRING = myMenu.Menu.popup.MenuItem[2].onClick;
Das folgende EGL-Wörterverzeichnis spiegelt das aktuelle Beispiel wider:
myMenu Dictionary
{  Menu = new Dictionary
   { id = "file",
     value = "File",
     popup = new Dictionary 
     { MenuItem = new Dictionary[]
       { new dictionary {value = "New", onClick = "CreateNewDoc()" },
         new dictionary {value = "Open", onClick = "OpenDoc()" },
         new dictionary {value = "Close", onClick = "CloseDoc()"}
       } 
     } 
   }
};     
Um mit der Funktion 'serviceLib.convertToJSON()' zu arbeiten, erstellen Sie zunächst ein Wörterverzeichnis, das wie in den vorherigen Beispielen strukturiert ist. Es gelten die folgenden beiden Regeln:
  • Jedes Wörterverzeichnis in einer Wörterverzeichnishierarchie ist äquivalent zu einer in Klammern eingeschlossenen Klausel in der JSON-Zeichenfolge.
  • Jedem Schlüssel wird ein Basiselementwert, ein Wörterverzeichnis, ein Datensatz oder eine Feldgruppe aus Wörterverzeichnissen bzw. Datensätzen zugeordnet.

Um mehr darüber zu erfahren, wie ein Wörterverzeichnisdatensatz beim Zugriff auf eine JSON-Zeichenfolge verwendet wird, lesen Sie die Informationen im Rich UI-Beispiel 'geocode.dictionaries'.

JSON und Datensätze sowie Wörterverzeichnisse

In den folgenden Fällen können Datensätze und Wörterverzeichnisse auch gemischt verwendet werden:
  • Wenn Sie den Aufruf von 'serviceLib.convertFromJSON()' mit einem Datensatz vorbereiten.
  • Wenn Sie den Aufruf von 'serviceLib.convertToJSON()' mit einem Datensatz oder einem Wörterverzeichnis vorbereiten.
Sie könnten ein Wörterverzeichnis in einen Datensatz einschließen, um auf die folgende JSON-Zeichenfolge zuzugreifen:
{"Result":{"Timestamp":1191871152}}
Sie können den folgenden Abschnitt definieren:
Record ResultRecordPart
   Result Dictionary;
end
Ihr Code kann wie folgt auf den Wert der Zeitmarke (Timestamp) zugreifen:
   myResult ResultRecordPart;
   milliseconds BIGINT;
		serviceLib.convertFromJSON(resp.body, myResult);
		milliseconds = myResult.Result["Timestamp"] as BIGINT;
Als allgemeine Regel gilt, dass bei der Zuordnung einer eingehenden JSON-Klausel zu einem Wörterverzeichnis nur dann auf die Daten in der Klausel zugegriffen werden kann, wenn eine Wörterverzeichnissyntax verwendet wird. Es folgt ein komplexes Beispiel hierzu:
{"Menu": 
  { "id": "file", "value": "File", "popup": 
     {"Menuitem": 
       [
         {"value": "New", "onClick": "CreateNewDoc()"},
         {"value": "Open", "onClick": "OpenDoc()"},
         {"value": "Close", "onClick": "CloseDoc()"}
       ]   
     }
  }
}
Um den Zugriff auf den Inhalt vorzubereiten, können Sie die folgenden Abschnitte definieren:
Record MyTopPart
   Menu MyMenuPart;
end

Record MyMenuPart
   id STRING; 
   value STRING;
   popup Dictionary; 
end
Das folgende EGL-Wörterverzeichnis spiegelt die Struktur namens popup wider:
   popup Dictionary 
   { MenuItem = new Dictionary[]
      { new Dictionary {value = "New", onClick = "CreateNewDoc()" },
        new Dictionary {value = "Open", onClick = "OpenDoc()" },
        new Dictionary {value = "Close", onClick = "CloseDoc()"}
      } 
   } 

(Dieses Wörterverzeichnis wird zwecks Veranschaulichung gezeigt. Die Unterstruktur eines Wörterverzeichnisses kann nützlich sein, wenn Sie die Funktion 'serviceLib.convertToJSON()' aufrufen, wird jedoch beim Aufrufen von 'serviceLib.convertFromJSON()' nicht verwendet.)

Mit dem folgenden Code wird auf die Zeichenfolge "OpenDoc()" zugegriffen:
   myTop MyTopPart;
   itemString STRING;
   serviceLib.convertFromJSON(resp.body, myTop);
   itemString = myTop.Menu.popup.MenuItem[2].onClick;

Feedback