Freigegebene Azure JSON-Bibliothek für Java – Version 1.1.0

Azure JSON bietet freigegebene Grundtypen, Abstraktionen und Hilfsprogramme für JSON.

Erste Schritte

Voraussetzungen

• Java Development Kit (JDK), Version 8 oder höher.

Einschließen des Pakets

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-json</artifactId>
  <version>1.1.0</version>
</dependency>

Wichtige Begriffe

JsonSerializable

JsonSerializable wird verwendet, um zu definieren, wie ein Objekt json-serialisiert und deserialisiert wird, indem die Serialisierung im Streamstil verwendet wird, wobei das Objekt selbst die Logik für die Verarbeitung verwaltet. Die Schnittstelle stellt eine instance-basierte toJson API bereit, die das Schreiben des Objekts in eine JsonWriter und eine statische fromJson API verarbeitet, die Implementierungen bereitstellen müssen, um zu definieren, wie ein Objekt erstellt wird, indem aus gelesen JsonReaderwird, wenn eine Implementierung nicht bereitgestellt UnsupportedOperationException wird.

JsonToken

JsonToken ist eine einfache Enumeration, die den aktuellen Zustand in einem JSON-Stream angibt.

JsonReader

JsonReader bietet sowohl grundlegende , lesen primitive und boxed primitive Typen, als auch Komfort beim Lesen von Arrays, Zuordnungen und Objekten, APIs zum Lesen von JSON. JsonReader wird bereitgestellt, um es jedem zugrunde liegenden JSON-Parser zu ermöglichen, ihn zu implementieren, z. B. Jackson oder GSON, solange die Implementierung die Tests besteht, die von der test-jar (JsonReaderContractTests) dieses Pakets bereitgestellt werden.

JsonReader wird erst im JSON-Stream vorwärts vorwärts ausgeführt, bis nextToken aufgerufen wird, was bedeutet, dass JsonReader.getInt dies auf unbestimmte Zeit aufgerufen werden kann, um dieselbe ganze Zahl ohne Fehler zurückzugeben, bis nextToken der JSON-Stream vorwärts voranschreitet.

JsonReader ermöglicht die Typkonvertierung zwischen JSON-Typen, z. B. den Versuch, eine JSON-Zeichenfolge in eine Zahl zu konvertieren oder umgekehrt, und für häufig verwendete nicht standardmäßige JSON-Werte wie NaN, , INF, -INF, Infinityund -Infinity.

JsonReader übernimmt nicht den Besitz der JSON-Eingabequelle und schließt daher keine Ressourcen, wenn der JSON-Code mit einem InputStream oder Readerbereitgestellt wird.

Schachtelungsgrenzwerte

JsonReaderDie generische readUntyped API verfolgt, wie tief geschachtelt das zu lesende Objekt ist. Wenn die Schachtelung den Schwellenwert von 1000überschreitet, IllegalStateException wird ausgelöst, um zu verhindern StackOverflowError.

JsonWriter

JsonWriter bietet sowohl grundlegende, schreibgrund- und boxed-primitive Typen als auch Komfort beim Schreiben von Arrays, Zuordnungen und Objekten, APIs zum Schreiben von JSON. JsonWriter wird bereitgestellt, um es jedem zugrunde liegenden JSON-Writer zu ermöglichen, ihn zu implementieren, z. B. Jackson oder GSON, solange die Implementierung die Tests besteht, die von der test-jar (JsonWriterContractTests) des Pakets bereitgestellt werden.

JsonWriterermöglicht es, dass häufig verwendete nicht standardmäßige JSON-Werte wie NaN, INF, -INF, Infinityund -Infinitymit oder writeRawValuegeschrieben writeNumberField werden.

JsonWriterschreibt keine NULL -byte[], , , Number- oder String -Werte, wenn als Feld, writeBinaryField, writeBooleanField, writeNumberFieldoder writeStringFieldgeschrieben wird, wenn ein NULL-Feld geschrieben werden muss, verwenden writeNullFieldSie . Boolean

JsonWriter muss in regelmäßigen Abständen geleert werden, um sicherzustellen, dass der in ihn geschriebene Inhalt in den zugrunde liegenden Containertyp geleert wird, in der Regel ein OutputStream oder Writer. Ein Fehler beim Leeren kann zum Verlust von Inhalten führen. Wenn Sie den Inhalt leeren JsonWriter , empfiehlt es sich daher, in einem Try-with-Resources-Block zu verwenden JsonWriter , in dem der JsonWriter geschlossen wird, sobald die Verwendung abgeschlossen ist.

JsonWriter übernimmt nicht den Besitz der JSON-Ausgabequelle und schließt daher keine Ressourcen, wenn der JSON-Code in ein OutputSteam oder Writergeschrieben wird.

JSON-Zustandsverwaltung

Um sicherzustellen, dass der zu schreibende JSON-Code gültig ist, behält den Zustand des JSON-Codes bei, JsonWriter und JsonWriteContext bei jedem Schreibversuch wird überprüft, ob der Vorgang gültig ist. Die Implementierung von JsonWriter muss sicherstellen, dass der Zustand ordnungsgemäß nachverfolgt wird, z. B. wenn nichts geschrieben wurde, muss der JSON-Zustand sein ROOT und ROOT lässt das Schreiben von JSON-Feldnamen nicht zu.

JsonProvider

JsonProvider ist eine Dienstanbieterschnittstelle, mit JsonReaderder s und JsonWriters mithilfe von Implementierungen im Klassenpfad erstellt werden können. JsonProvider kann auch die Standardimplementierungen erstellen, die von diesem Paket bereitgestellt werden, wenn keine Implementierung im Klassenpfad gefunden wird.

JsonOptions

JsonOptions enthält Konfigurationen, die von allen Implementierungen von JsonReaders und JsonWriters beachtet werden müssen. Derzeit gibt es nur eine Konfiguration zum Bestimmen, ob nicht numerische Zahlen, NaN, INF, -INF, Infinityund -Infinity beim JSON-Lesen und -Schreiben mit der Standardeinstellung unterstützt truewerden, dass nicht numerische Zahlen zulässig sind.

Bereitstellen einer SPI-Implementierung

JsonReader und JsonWriter sind Dienstanbieterschnittstellen, die von JsonProvider und JsonProviders verwendet werden, um das Laden von Implementierungen aus dem Klassenpfad zu ermöglichen. Das Azure JSON-Paket stellt eine Standardimplementierung bereit, die verwendet wird, wenn sie im Klassenpfad nicht gefunden werden kann. Um eine benutzerdefinierte Implementierung bereitzustellen, implementieren Sie JsonReader, JsonWriterund JsonProvider in Ihr eigenes Paket, und geben Sie an, dass das Paket eine instance von JsonProviderbereitstellt. Um sicherzustellen, dass Ihre Implementierungen korrekt sind, schließen Sie die test bereichsbezogene Abhängigkeit von Azure JSON ein, und erweitern Sie die JsonReaderContractTests, JsonWriterContractTestsund JsonProviderContractTests. In diesen Tests werden alle grundlegenden Vertragsanforderungen beschrieben, die von , JsonWriterund und festgelegt sindJsonReader, und JsonProvider einige komplexe Szenarien testen, um eine Validierung jeder Implementierung zu ermöglichen.

Beispiele

Ausführliche Beispiele zur Verwendung von Azure JSON finden Sie in der Infodatei zu den Beispielen .

Problembehandlung

Wenn Fehler auftreten, senden Sie Probleme über GitHub Issues oder checken Sie StackOverflow für das Azure Java SDK aus.

Nächste Schritte

Erste Schritte mit Azure-Bibliotheken, die mit Azure Core erstellt werden.

Mitwirken

Ausführliche Informationen zum Mitwirken zu diesem Repository finden Sie im Leitfaden zur Mitarbeit.

1. Fork
2. Erstellen Ihres Featurebranch (git checkout -b my-new-feature)
3. Commit für Ihre Änderungen (git commit -am 'Add some feature')
4. Pushen an den Branch (git push origin my-new-feature)
5. Erstellen eines neuen Pull Request