This commit is contained in:
azure-sdk 2022-09-22 21:28:29 +00:00
Родитель c0c3c06b69
Коммит da442281d4
6 изменённых файлов: 505 добавлений и 0 удалений

Просмотреть файл

@ -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
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-json-gson</artifactId>
<version>1.0.0-beta.1</version>
</dependency>
```
[//]: # ({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
<!-- links -->
[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)

Просмотреть файл

@ -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
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-json</artifactId>
<version>1.0.0-beta.1</version>
</dependency>
```
[//]: # ({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<JsonSerializableExample> {
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
<!-- links -->
[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)

Просмотреть файл

@ -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
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-xml</artifactId>
<version>1.0.0-beta.1</version>
</dependency>
```
[//]: # ({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<XmlSerializableExample> {
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
<!-- links -->
[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)

Просмотреть файл

@ -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"
}

Просмотреть файл

@ -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"
}

Просмотреть файл

@ -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"
}