diff --git a/docs-ref-services/preview/json-gson-readme.md b/docs-ref-services/preview/json-gson-readme.md new file mode 100644 index 000000000000..4d0785816ddb --- /dev/null +++ b/docs-ref-services/preview/json-gson-readme.md @@ -0,0 +1,72 @@ +--- +title: Azure GSON JSON shared library for Java +keywords: Azure, java, SDK, API, azure-json-gson, core +author: alzimmermsft +ms.author: alzimmer +ms.date: 09/22/2022 +ms.topic: reference +ms.devlang: java +ms.service: core +--- +# Azure GSON JSON shared library for Java - version 1.0.0-beta.1 + + +[![Build Documentation](https://img.shields.io/badge/documentation-published-blue.svg)](https://azure.github.io/azure-sdk-for-java) + +Azure GSON JSON provides an implementation of `azure-json` using GSON. + +## Getting started + +### Prerequisites + +- A [Java Development Kit (JDK)][jdk_link], version 8 or later. + +### Include the package + +#### Include direct dependency + +If you want to take dependency on a particular version of the library that is not present in the BOM, +add the direct dependency to your project as follows. + +[//]: # ({x-version-update-start;com.azure:azure-json-gson;current}) +```xml + + com.azure + azure-json-gson + 1.0.0-beta.1 + +``` +[//]: # ({x-version-update-end}) + +## Key concepts + +See `azure-json` for key concepts. + +## Examples + +See `azure-json` for examples. + +## Next steps + +Get started with Azure libraries that are [built using Azure Core](https://azure.github.io/azure-sdk/releases/latest/#java). + +## Troubleshooting + +If you encounter any bugs, please file issues via [GitHub Issues](https://github.com/Azure/azure-sdk-for-java/issues/new/choose) +or checkout [StackOverflow for Azure Java SDK](https://stackoverflow.com/questions/tagged/azure-java-sdk). + +## Contributing + +For details on contributing to this repository, see the [contributing guide](https://github.com/Azure/azure-sdk-for-java/blob/azure-json-gson_1.0.0-beta.1/CONTRIBUTING.md). + +1. Fork it +2. Create your feature branch (`git checkout -b my-new-feature`) +3. Commit your changes (`git commit -am 'Add some feature'`) +4. Push to the branch (`git push origin my-new-feature`) +5. Create new Pull Request + + +[jdk_link]: /java/azure/jdk/?view=azure-java-stable + +![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Fcore%2Fazure-json-gson%2FREADME.png) + diff --git a/docs-ref-services/preview/json-readme.md b/docs-ref-services/preview/json-readme.md new file mode 100644 index 000000000000..683f4c908257 --- /dev/null +++ b/docs-ref-services/preview/json-readme.md @@ -0,0 +1,211 @@ +--- +title: Azure JSON shared library for Java +keywords: Azure, java, SDK, API, azure-json, core +author: alzimmermsft +ms.author: alzimmer +ms.date: 09/22/2022 +ms.topic: reference +ms.devlang: java +ms.service: core +--- +# Azure JSON shared library for Java - version 1.0.0-beta.1 + + +[![Build Documentation](https://img.shields.io/badge/documentation-published-blue.svg)](https://azure.github.io/azure-sdk-for-java) + +Azure JSON provides shared primitives, abstractions, and helpers for JSON. + +## Getting started + +### Prerequisites + +- A [Java Development Kit (JDK)][jdk_link], version 8 or later. + +### Include the package + +#### Include direct dependency + +If you want to take dependency on a particular version of the library that is not present in the BOM, +add the direct dependency to your project as follows. + +[//]: # ({x-version-update-start;com.azure:azure-json;current}) +```xml + + com.azure + azure-json + 1.0.0-beta.1 + +``` +[//]: # ({x-version-update-end}) + +## Key concepts + +### JsonSerializable + +`JsonSerializable` is used to define how an object is JSON serialized and deserialized using stream-style serialization +where the object itself manages the logic for how it's handled with JSON. The interface provides an instance-based +`toJson` API which handles writing the object to a `JsonWriter` and a static `fromJson` API which implementations must +override to define how an object is created by reading from a `JsonReader`. + +### JsonToken + +`JsonToken` is a basic enum that indicates the current state in a JSON stream. + +### JsonReader + +`JsonReader` provides both basic, reading primitive and boxed primitive types, and convenience, reading arrays, maps, +and objects, APIs for reading JSON. `JsonReader` is provided to allow for any underlying JSON parser to implement it, +such as Jackson or GSON, as long as the implementation passes the tests provided by this package's test-jar +(`JsonReaderContractTests`). + +`JsonReader` doesn't progress forward in the JSON stream until `nextToken` is called, meaning that `JsonReader.getInt` +could be called indefinitely returning the same integer without error until `nextToken` progresses the JSON stream +forward. + +`JsonReader` allows for type conversion between JSON types, such as trying to convert a JSON string to a number or vice +versa, and for commonly used non-standard JSON values, such as `NaN`, `INF`, `-INF`, `Infinity`, and `-Infinity`. + +`JsonReader` doesn't take ownership of the JSON input source and therefore won't close any resources if the JSON is +provided using an `InputStream` or `Reader`. + +#### Nesting Limits + +To prevent `StackOverflowError`s `JsonReader`'s generic `readUntyped` API tracks how deeply nested the object being read +is, if the nesting passes the threshold of `1000` an `IllegalStateException` will be thrown in an attempt to prevent +the stack from overflowing. + +### JsonWriter + +`JsonWriter` provides both basic, writing primitives and boxed primitive types, and convenience, writing arrays, maps, +and objects, APIs for writing JSON. `JsonWriter` is provided to allow for any underlying JSON writer to implement it, +such as Jackson or GSON, as long as the implementation passes the tests provided by this package's test-jar +(`JsonWriterContractTests`). + +`JsonWriter` allows for commonly used non-standard JSON values, such as `NaN`, `INF`, `-INF`, `Infinity`, and +`-Infinity`, to be written using `writeNumberField` or `writeRawValue`. + +`JsonWriter` won't write null `byte[]`, `Boolean`, `Number`, or `String` values when written as a field, +`writeBinaryField`, `writeBooleanField`, `writeNumberField`, or `writeStringField`, if a null field needs to be written +use `writeNullField`. + +`JsonWriter` must be periodically flushed to ensure content written to it is flushed to the underlying container type, +generally an `OutputStream` or `Writer`. Failing to flush may result in content being lost. Closing the `JsonWriter` +will also flush content, so it's best practice to use `JsonWriter` in a try-with-resources block where the `JsonWriter` +will be closed once it's finished being used. + +`JsonWriter` doesn't take ownership of the JSON output source and therefore won't close any resources if the JSON is +being written to an `OutputSteam` or `Writer`. + +#### JSON State Management + +To ensure that the JSON being written is valid `JsonWriter` will maintain the state of the JSON using `JsonWriteContext` +and on each attempt to write it will validate whether the operation is valid. The implementation of `JsonWriter` must +ensure this is tracked correctly, for example when nothing has been written the JSON state must be `ROOT` and `ROOT` +doesn't allow for JSON field names to be written. + +### JsonProvider + +`JsonProvider` is a service provider interface which allows for `JsonReader`s and `JsonWriter`s to be created using +implementations found on the classpath. `JsonProvider` can also create the default implementations which are provided +by this package if an implementation isn't found on the classpath. + +#### JsonOptions + +`JsonOptions` contains configurations that are respected by all implementations of `JsonReader`s and `JsonWriter`s. At +this time there is only one configuration for determining whether non-numeric numbers, `NaN`, `INF`, `-INF`, `Infinity`, +and `-Infinity` are supported in JSON reading and writing with a default setting of `true`, that non-numeric numbers +are allowed. + +## Examples + +### JsonSerializable + +```java jsonserializablesample-basic +public class JsonSerializableExample implements JsonSerializable { + private int anInt; + private boolean aBoolean; + private String aString; + private Double aNullableDecimal; + + @Override + public JsonWriter toJson(JsonWriter jsonWriter) throws IOException { + jsonWriter.writeStartObject(); + + jsonWriter.writeIntField("anInt", anInt); + jsonWriter.writeBooleanField("aBoolean", aBoolean); + jsonWriter.writeStringField("aString", aString); + // writeNumberField doesn't write the field if the value is null, if a null field is explicitly needed + // null checking and using writeNullField should be used. + jsonWriter.writeNumberField("aNullableDecimal", aNullableDecimal); + + // Example of null checking: + // if (aNullableDecimal == null) { + // jsonWriter.writeNullField("aNullableDecimal"); + // } else { + // jsonWriter.writeNumberField("aNullableDecimal", aNullableDecimal); + // } + + return jsonWriter.writeEndObject(); + } + + public JsonSerializableExample fromJson(JsonReader jsonReader) throws IOException { + // readObject is a convenience method on JsonReader which prepares the JSON for being read as an object. + // If the current token isn't initialized it will begin reading the JSON stream, then if the current token + // is still null or JsonToken.NULL null will be returned without calling the reader function. If the + // current token isn't a valid object state an exception will be thrown, and if it is a valid object state + // the reader function will be called. + return jsonReader.readObject(reader -> { + // Since this class has no constructor reading to fields can be done inline. + // If the class had a constructor with arguments the recommendation is using local variables to track + // all field values. + JsonSerializableExample result = new JsonSerializableExample(); + while (reader.nextToken() != JsonToken.END_OBJECT) { + String fieldName = reader.getFieldName(); + if ("anInt".equals(fieldName)) { + result.anInt = reader.getInt(); + } else if ("aBoolean".equals(fieldName)) { + result.aBoolean = reader.getBoolean(); + } else if ("aString".equals(fieldName)) { + result.aString = reader.getString(); + } else if ("aNullableDecimal".equals(fieldName)) { + // getNullable returns null if the current token is JsonToken.NULL, if the current token isn't + // JsonToken.NULL it passes the reader to the ReadValueCallback. + result.aNullableDecimal = reader.getNullable(JsonReader::getDouble); + } else { + // Skip children when the field is unknown. + // If the current token isn't an array or object this is a no-op, otherwise is skips the entire + // sub-array/sub-object. + reader.skipChildren(); + } + } + + return result; + }); + } +} +``` + +## Next steps + +Get started with Azure libraries that are [built using Azure Core](https://azure.github.io/azure-sdk/releases/latest/#java). + +## Troubleshooting + +If you encounter any bugs, please file issues via [GitHub Issues](https://github.com/Azure/azure-sdk-for-java/issues/new/choose) +or checkout [StackOverflow for Azure Java SDK](https://stackoverflow.com/questions/tagged/azure-java-sdk). + +## Contributing + +For details on contributing to this repository, see the [contributing guide](https://github.com/Azure/azure-sdk-for-java/blob/azure-json_1.0.0-beta.1/CONTRIBUTING.md). + +1. Fork it +2. Create your feature branch (`git checkout -b my-new-feature`) +3. Commit your changes (`git commit -am 'Add some feature'`) +4. Push to the branch (`git push origin my-new-feature`) +5. Create new Pull Request + + +[jdk_link]: /java/azure/jdk/?view=azure-java-stable + +![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Fcore%2Fazure-json%2FREADME.png) + diff --git a/docs-ref-services/preview/xml-readme.md b/docs-ref-services/preview/xml-readme.md new file mode 100644 index 000000000000..fccba36489df --- /dev/null +++ b/docs-ref-services/preview/xml-readme.md @@ -0,0 +1,180 @@ +--- +title: Azure XML shared library for Java +keywords: Azure, java, SDK, API, azure-xml, core +author: alzimmermsft +ms.author: alzimmer +ms.date: 09/22/2022 +ms.topic: reference +ms.devlang: java +ms.service: core +--- +# Azure XML shared library for Java - version 1.0.0-beta.1 + + +[![Build Documentation](https://img.shields.io/badge/documentation-published-blue.svg)](https://azure.github.io/azure-sdk-for-java) + +Azure XML provides shared primitives, abstractions, and helpers for XML. + +## Getting started + +### Prerequisites + +- A [Java Development Kit (JDK)][jdk_link], version 8 or later. + +### Include the package + +#### Include direct dependency + +If you want to take dependency on a particular version of the library that is not present in the BOM, +add the direct dependency to your project as follows. + +[//]: # ({x-version-update-start;com.azure:azure-xml;current}) +```xml + + com.azure + azure-xml + 1.0.0-beta.1 + +``` +[//]: # ({x-version-update-end}) + +## Key concepts + +### XmlSerializable + +`XmlSerializable` is used to define how an object is XML serialized and deserialized using stream-style serialization +where the object itself manages the logic for how it's handled with XML. The interface provides an instance-based +`toXml` API which handles writing the object to an `XmlWriter` and a static `fromXml` API which implementations must +override to define how an object is created by reading from an `XmlReader`. + +### XmlToken + +`XmlToken` is a basic enum that indicates the current state in an XML stream. + +### XmlReader + +`XmlReader` provides both basic, reading primitive and boxed primitive types, and convenience, reading an object, APIs +for reading XML. `XmlReader` is provided to allow for any underlying XML parser to implement it, such as Woodstox or +XMLStreamReader, as long as the implementation passes the tests provided by this package's test-jar +(`XmlReaderContractTests`). + +`XmlReader` is a simplified XML parser where it only supports reading element-by-element with the ability to retrieve +the namespace and attributes for that element. `XmlReader` doesn't progress forward in the XML stream until +`nextElement` is called, meaning that `XmlReader.getIntElement` could be called indefinitely returning the same integer +without error until `nextElement` progresses the XML stream forward. + +`XmlReader` doesn't take ownership of the XML input source and therefore won't close any resources if the XML is +provided using an `InputStream` or `Reader`. + +### XmlWriter + +`XmlWriter` provides basic APIs for writing XML. `XmlWriter` is provided to allow for any underlying XML writer to +implement it, such as Woodstox or XMLStreamWriter, as long as the implementation passes the tests provided by this +package's test-jar (`XmlWriterContractTests`). + +`XmlWriter` must be periodically flushed to ensure content written to it is flushed to the underlying container type, +generally an `OutputStream` or `Writer`. Failing to flush may result in content being lost. Closing the `XmlWriter` will +also flush content, so it's best practice to use `XmlWriter` in a try-with-resources block where the `XmlWriter` will +be closed once it's finished being used. + +`XmlWriter` doesn't take ownership of the XML output source and therefore won't close any resources if the XML is being +written to an `OutputStream` or `Writer`. + +### XmlProvider + +`XmlProvider` is a service provider interface which allows for `XmlReader`s and `XmlWriter`s to be created using +implementations found on the classpath. `XmlProvider` can also create the default implementations which are provided by +this package if an implementation isn't found on the classpath. + +## Examples + +### XmlSerializable + +```java xmlserializablesample-basic +public class XmlSerializableExample implements XmlSerializable { + private boolean aBooleanAttribute; + private Double aNullableDecimalAttribute; + private int anIntElement; + private String aStringElement; + + @Override + public XmlWriter toXml(XmlWriter xmlWriter) throws XMLStreamException { + xmlWriter.writeStartElement("example"); + + // Writing attributes must happen first so that they are written to the object start element. + xmlWriter.writeBooleanAttribute("aBooleanAttribute", aBooleanAttribute); + xmlWriter.writeNumberAttribute("aNullableDecimalAttribute", aNullableDecimalAttribute); + + xmlWriter.writeIntElement("anIntElement", anIntElement); + xmlWriter.writeStringElement("aStringElement", aStringElement); + + return xmlWriter.writeEndElement(); + } + + public XmlSerializableExample fromXml(XmlReader xmlReader) throws XMLStreamException { + // readObject is a convenience method on XmlReader which prepares the XML for being read as an object. + // If the current token isn't an XmlToken.START_ELEMENT the next token element will be iterated to, if it's + // still not an XmlToken.START_ELEMENT after iterating to the next element an exception will be thrown. If + // the next element is an XmlToken.START_ELEMENT it will validate that the XML element matches the name + // expected, if the name doesn't match an exception will be thrown. If the element name matches the reader + // function will be called. + return xmlReader.readObject("example", reader -> { + // Since this class has no constructor reading to fields can be done inline. + // If the class had a constructor with arguments the recommendation is using local variables to track + // all field values. + + XmlSerializableExample result = new XmlSerializableExample(); + + // Reading attributes must happen first so that the XmlReader is looking at the object start element. + result.aBooleanAttribute = reader.getBooleanAttribute(null, "aBooleanAttribute"); + result.aNullableDecimalAttribute = reader.getNullableAttribute(null, "aNullableDecimalAttribute", + Double::parseDouble); + + while (reader.nextElement() != XmlToken.END_ELEMENT) { + QName elementName = reader.getElementName(); + + // Since this object doesn't use namespaces we can work with the local part directly. + // If it had namespaces the full QName would need to be inspected. + String localPart = elementName.getLocalPart(); + if ("anIntElement".equals(localPart)) { + result.anIntElement = reader.getIntElement(); + } else if ("aStringElement".equals(localPart)) { + // getStringElement coalesces XML text and XML CData into a single string without needing to + // manage state. + result.aStringElement = reader.getStringElement(); + } else { + // Skip element when the element is unknown. + reader.skipElement(); + } + } + + return result; + }); + } +} +``` + +## Next steps + +Get started with Azure libraries that are [built using Azure Core](https://azure.github.io/azure-sdk/releases/latest/#java). + +## Troubleshooting + +If you encounter any bugs, please file issues via [GitHub Issues](https://github.com/Azure/azure-sdk-for-java/issues/new/choose) +or checkout [StackOverflow for Azure Java SDK](https://stackoverflow.com/questions/tagged/azure-java-sdk). + +## Contributing + +For details on contributing to this repository, see the [contributing guide](https://github.com/Azure/azure-sdk-for-java/blob/azure-xml_1.0.0-beta.1/CONTRIBUTING.md). + +1. Fork it +2. Create your feature branch (`git checkout -b my-new-feature`) +3. Commit your changes (`git commit -am 'Add some feature'`) +4. Push to the branch (`git push origin my-new-feature`) +5. Create new Pull Request + + +[jdk_link]: /java/azure/jdk/?view=azure-java-stable + +![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Fcore%2Fazure-xml%2FREADME.png) + diff --git a/metadata/preview/azure-json-gson.json b/metadata/preview/azure-json-gson.json new file mode 100644 index 000000000000..85dbf608251a --- /dev/null +++ b/metadata/preview/azure-json-gson.json @@ -0,0 +1,14 @@ +{ + "Name": "azure-json-gson", + "Version": "1.0.0-beta.1", + "DevVersion": null, + "DirectoryPath": "sdk/core/azure-json-gson", + "ServiceDirectory": "core", + "ReadMePath": "sdk/core/azure-json-gson/README.md", + "ChangeLogPath": "sdk/core/azure-json-gson/CHANGELOG.md", + "Group": "com.azure", + "SdkType": "client", + "IsNewSdk": true, + "ArtifactName": "azure-json-gson", + "ReleaseStatus": "2022-09-22" +} diff --git a/metadata/preview/azure-json.json b/metadata/preview/azure-json.json new file mode 100644 index 000000000000..50ae273f79f4 --- /dev/null +++ b/metadata/preview/azure-json.json @@ -0,0 +1,14 @@ +{ + "Name": "azure-json", + "Version": "1.0.0-beta.1", + "DevVersion": null, + "DirectoryPath": "sdk/core/azure-json", + "ServiceDirectory": "core", + "ReadMePath": "sdk/core/azure-json/README.md", + "ChangeLogPath": "sdk/core/azure-json/CHANGELOG.md", + "Group": "com.azure", + "SdkType": "client", + "IsNewSdk": true, + "ArtifactName": "azure-json", + "ReleaseStatus": "2022-09-22" +} diff --git a/metadata/preview/azure-xml.json b/metadata/preview/azure-xml.json new file mode 100644 index 000000000000..cde7dd5aa10a --- /dev/null +++ b/metadata/preview/azure-xml.json @@ -0,0 +1,14 @@ +{ + "Name": "azure-xml", + "Version": "1.0.0-beta.1", + "DevVersion": null, + "DirectoryPath": "sdk/core/azure-xml", + "ServiceDirectory": "core", + "ReadMePath": "sdk/core/azure-xml/README.md", + "ChangeLogPath": "sdk/core/azure-xml/CHANGELOG.md", + "Group": "com.azure", + "SdkType": "client", + "IsNewSdk": true, + "ArtifactName": "azure-xml", + "ReleaseStatus": "2022-09-22" +}