Java, readme update (#311)

* Readme update in template

* Readmes updated

* Readme updated

* Redme updated, dict references changed to map

Author: spacether

samples/client/3_0_3_unit_test/java/README.md

@@ -9,97 +9,113 @@ This Java package is automatically generated by the [OpenAPI JSON Schema Generat
 
 ## Requirements
 
-Java 17
+1. Java 17
+2. Gradle
 
 ## Migration Guides
-- [3.0.0 Migration Guide](migration_3_0_0.md)
-- [2.0.0 Migration Guide](migration_2_0_0.md)
-- [Migration from Other Python Generators](migration_other_python_generators.md)
+- [Migration from Other Java Generators](migration_other_java_generators.md)
 
 
 ## Installation
-### pip install
 
-If the python package is hosted on a repository, you can install directly using:
+To install the API client library to your local Maven repository, simply execute:
 
-```sh
-pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git
+```shell
+mvn clean install
 ```
-(you may need to run `pip` with root permission: `sudo pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git`)
 
-Then import the package:
-```python
-import org.openapijsonschematools.client
+To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:
+
+```shell
+mvn clean deploy
 ```
 
-### Setuptools
+Refer to the [OSSRH Guide](http://central.sonatype.org/pages/ossrh-guide.html) for more information.
+
+### Maven users
 
-Install via [Setuptools](http://pypi.python.org/pypi/setuptools).
+Add this dependency to your project's POM:
 
-```sh
-python -m pip install . --user
+```xml
+<dependency>
+  <groupId>org.openapijsonschematools</groupId>
+  <artifactId>petstore</artifactId>
+  <version>0.0.1</version>
+  <scope>compile</scope>
+</dependency>
 ```
-(or `python -m pip install .` to install the package for all users)
 
-Then import the package:
-```python
-import org.openapijsonschematools.client
+### Others
+
+At first generate the JAR by executing:
+
+```shell
+mvn clean package
 ```
 
+Then manually install the following JARs:
+
+- `target/petstore-0.0.1.jar`
+- `target/lib/*.jar`
+
+
 ## Usage Notes
 ### Validation, Immutability, and Data Type
-This python code validates data to schema classes and return back an immutable instance containing the data
-which subclasses all validated schema classes. This ensure that
+This Java code validates data to schema classes and return back an immutable instance containing the data. This ensure that
 - valid data cannot be mutated and become invalid to a set of schemas
   - the one exception is that files are not immutable, so schema instances storing/sending/receiving files are not immutable
 
-Here is the mapping from json schema types to python subclassed types:
+Here is the mapping from json schema types to Java types:
+
 | Json Schema Type | Java Base Class |
-| ---------------- | ----------------- |
+| ---------------- | --------------- |
 | object           | FrozenMap (HashMap) |
 | array            | FrozenList (ArrayList) |
 | string           | String |
-| number           | Number, float, double, int, long |
-| integer          | int, long |
+| number           | Number (int, long, float, double) |
+| integer          | int, long, float, double (with values equal to integers) |
 | boolean          | boolean |
 | null             | Void (null) |
 | AnyType (unset)  | Object |
 
-### Storage of Json Schema Definition in Python Classes
+### Storage of Json Schema Definition in Java JsonSchema Classes
 In openapi v3.0.3 there are ~ 28 json schema keywords. Almost all of them can apply if
-type is unset. I have chosen to separate the storage of json schema definition info and output
-validated classes for payload instantiation.
+type is unset. I have chosen to separate the storage of
+- json schema definition info
+- output classes for validated Map (json schema type object) payloads
+- output classes for validated List (json schema type array) payloads
 
 <details>
   <summary>Reason</summary>
 
 This json schema data is stored in each class that is written for a schema, in a component or
 other openapi document location. This class is only responsible for storing schema info.
-Output classes like those that store dict payloads are written separately and are
-returned by the Schema.validate method when that method is passed in dict input.
+Output classes like those that store map payloads are written separately and are
+returned by the JsonSchema.validate method when that method is passed in Map input.
 This prevents payload property access methods from
 colliding with json schema definition.
 </details>
 
 ### Json Schema Type Object
 Most component schemas (models) are probably of type object. Which is a map data structure.
 Json schema allows string keys in this map, which means schema properties can have key names that are
-invalid python variable names. Names like:
+invalid Java variable names. Names like:
 - "hi-there"
 - "1variable"
 - "@now"
 - " "
 - "from"
 
-To allow these use cases to work, schemas.immutabledict is used as the base class of type object schemas.
-This means that one can use normal dict methods on instances of these classes.
+To allow these use cases to work, FrozenMap (which extends HashMap) is used as the base class of type object schemas.
+This means that one can use normal Map methods on instances of these classes.
 
 <details>
   <summary>Other Details</summary>
 
-- optional properties which were not set will not exist in the instance
-- None is only allowed in as a value if type: "null" was included or nullable: true was set
-- preserving the original key names is required to properly validate a payload to multiple json schemas
+- getters are written for validly named required and optional properties
+- null is only allowed in as a value if type: "null" was included or nullable: true was set
+  - because null is an allowed property value, it is not used to represent an unset property state
+- if an optional property is requested and it does not exist in the Map, an UnsetPropertyException is thrown
 </details>
 
 ### Json Schema Type + Format, Validated Data Storage
@@ -131,24 +147,12 @@ is stored as a string.
 
 ## Getting Started
 
-Please follow the [installation procedure](#installation) and then run the following:
+Please follow the [installation procedure](#installation) and then use the JsonSchema classes in
+org.openapijsonschematools.client.components.schemas to validate input payloads and instances of validated Map and List
+output classes. Json schemas allow multiple types for one schema, so a schema's validate method can have
+allowed input and output types.
 
 
-## Servers
-| server_index | Class | Description |
-| ------------ | ----- | ----------- |
-| 0 | [Model0](docs/servers/0.md) | |
-
-## Endpoints
-
-All URIs are relative to the selected server
-- The server is selected by passing in server_info and server_index into api_configuration.ApiConfiguration
-- Code samples in endpoints documents show how to do this
-- server_index can also be passed in to endpoint calls, see endpoint documentation
-
-| HTTP request | Method | Description |
-| ------------ | ------ | ----------- |
-
 ## Component Schemas
 
 | Class | Description |
@@ -241,23 +245,3 @@ All URIs are relative to the selected server
 | [UriReferenceFormat.UriReferenceFormat1](docs/components/schemas/UriReferenceFormat.md#urireferenceformat1) | |
 | [UriTemplateFormat.UriTemplateFormat1](docs/components/schemas/UriTemplateFormat.md#uritemplateformat1) | |
 
-## Notes for Large OpenAPI documents
-If the OpenAPI document is large, imports in org.openapijsonschematools.client.apis.tags.tag_to_api and org.openapijsonschematools.client.components.schemass may fail with a
-RecursionError indicating the maximum recursion limit has been exceeded. In that case, there are a couple of solutions:
-
-Solution 1:
-Use specific imports for apis and models like:
-- tagged api: `from org.openapijsonschematools.client.apis.tags.default_api import DefaultApi`
-- api for one path: `from org.openapijsonschematools.client.apis.paths.some_path import SomePath`
-- api for one operation (path + verb): `from org.openapijsonschematools.client.paths.some_path.get import ApiForget`
-- single model import: `from org.openapijsonschematools.client.components.schemas.pet import Pet`
-
-Solution 2:
-Before importing the package, adjust the maximum recursion limit as shown below:
-```
-import sys
-sys.setrecursionlimit(1500)
-import org.openapijsonschematools.client
-from org.openapijsonschematools.client.apis.tags.tag_to_api import *
-from org.openapijsonschematools.client.components.schemass import *
-```