Sync open source content 🐝 (from 04ffca7aac108a871024d69503f3acfe6e45d9c3)

beezythebot · beezythebot · commit 0980a3453c37 · 2025-06-26T12:00:57.000Z
diff --git a/docs/languages/java/methodology-java.mdx b/docs/languages/java/methodology-java.mdx
@@ -14,7 +14,7 @@ The Speakeasy Java SDK is designed to be easy to use and debug. This includes ge
 The core features of the SDK include:
 
 - **Type-safety**: Strong typing is used extensively so that problems are seen at compile time, not runtime.
-- **Null-safety**: Primitive types are used where possible, improving **compile-time** null safety.  For non-required and nullable fields, the `java.util.Optional` and `JSONNullable` classes are used. Passing Java `null` arguments will provoke an exception. 
+- **Null-safety**: Primitive types are used where possible, improving **compile-time** null safety. For non-required and nullable fields, the `java.util.Optional` and `JSONNullable` classes are used. Passing Java `null` arguments will provoke an exception.
 - **Builders and method chaining for all SDK objects.** For example, to create a `Person` object:
 
 ```java
@@ -28,19 +28,19 @@ Person person = Person.builder()
 - All-field constructors are available for most SDK objects, so a user can get a compile-time indication of changes to the OpenAPI document if required.
 - **Readability**: Appropriately formatted method chaining is more understandable and maintainable.
 - **Discoverability**: Method chaining and favorable naming strategies make life easier. For example, to build a `Person` object, you call `Person.builder()` and **not** `new Builders.PersonFactory()`.
-- **Convenient overloads in builders.** For example, a `long` can be passed directly when the underlying field is `Optional<Long>`. 
+- **Convenient overloads in builders.** For example, a `long` can be passed directly when the underlying field is `Optional<Long>`.
 - The `java.util.Optional` class is used for non-required arguments.
-- The `JsonNullable` class is used for nullable arguments. 
-- The Java platform `OffsetDateTime` and `LocalDate` types are used for `date-time` and `date`. 
+- The `JsonNullable` class is used for nullable arguments.
+- The Java platform `OffsetDateTime` and `LocalDate` types are used for `date-time` and `date`.
 - A `utils` package provides shared code used by generated classes, making the generated code easier to follow.
 - Authentication support for OAuth flows and other standard security mechanisms.
 - Custom enum types using string or integer values.
-- Pagination support, including the option to return `java.util.Stream` so that paging is auto-handled. 
+- Pagination support, including the option to return `java.util.Stream` so that paging is auto-handled.
 - Well-formatted source code to make debugging easier.
 
 The SDK includes minimal dependencies. It requires:
 
-- [Jackson Library](https://github.com/FasterXML/jackson) to serialize and deserialize data over the wire. 
+- [Jackson Library](https://github.com/FasterXML/jackson) to serialize and deserialize data over the wire.
 - [Apache HttpClient](https://hc.apache.org/httpcomponents-client-4.5.x/index.html) to make HTTP requests.
 - [Jayway JsonPath](https://github.com/json-path/JsonPath) to support JSON path expressions in Speakeasy metadata fields in OpenAPI documents.
 
@@ -61,7 +61,7 @@ The SDK includes minimal dependencies. It requires:
 |           |   |   └-- ...
 |           |   └-- shared     # package for shared component models
 |           |       └-- ...
-|           └-- utils          # package for shared utility classes 
+|           └-- utils          # package for shared utility classes
 |               └-- ...
 |-- docs                           # Markdown files for the SDK's documentation
 |-- gradlew                        # Gradle shellscript to build/install the SDK
@@ -71,6 +71,7 @@ The SDK includes minimal dependencies. It requires:
 |   └-- ...                        # other Gradle-related files
 └-- ...
 ```
+
 ## Build customization
 
 The `build.gradle` file should not be edited because generation updates will overwrite changes. However, customization of `build.gradle` is possible:
@@ -82,34 +83,33 @@ The `build.gradle` file should not be edited because generation updates will ove
 java:
   version: 0.2.0
   artifactID: openapi
-...
-  additionalPlugins: 
-    - 'id("java")'
+---
+additionalPlugins:
+  - 'id("java")'
 ```
 
 Dependencies can be customized in two ways:
 
 - You can add a `dependencies` block to `build-extras.gradle`. Note that with standard Gradle techniques, you can exclude dependencies, exclude transitive dependencies, and modify dependencies in `build-extras.gradle`.
 
-- You can use the `additionalDependencies` property in `gen.yaml`. For example, the fragment below overrides the `jackson-databind`  and adds `commons-compress`:
+- You can use the `additionalDependencies` property in `gen.yaml`. For example, the fragment below overrides the `jackson-databind` and adds `commons-compress`:
 
   ```yaml
   java:
     version: 0.2.0
-  ...
-    addditionalDependencies:
-      - implementation:com.fasterxml.jackson.core:jackson-databind:2.16.0
-      - api:org.apache.commons:commons-compress:1.26.1
+  ---
+  addditionalDependencies:
+    - implementation:com.fasterxml.jackson.core:jackson-databind:2.16.0
+    - api:org.apache.commons:commons-compress:1.26.1
   ```
-  
 
 ## HTTP client
 
 The Java SDK HTTP client is configurable using a class implementing the following interface and is found in the `util` package of the generated code:
 
 ```java
 public interface HTTPClient {
-    public HTTPResponse<byte[]> send(HTTPRequest request) 
+    public HTTPResponse<byte[]> send(HTTPRequest request)
       throws IOException, InterruptedException, URISyntaxException
 }
 ```
@@ -126,7 +126,7 @@ This gives developers using your Java SDK the flexibility to set up proxies, coo
 
 ## Serialization and deserialization
 
-Low-level customizations like request and response hooks or `HTTPClient`-based interceptions may require the serialization and deserialization of generated objects to and from JSON. 
+Low-level customizations like request and response hooks or `HTTPClient`-based interceptions may require the serialization and deserialization of generated objects to and from JSON.
 
 You **must** use the generated custom Jackson `ObjectMapper` for these actions. The `ObjectMapper` is available as a Singleton in the generated `utils` package via `JSON.getMapper()`.
 
@@ -147,47 +147,47 @@ Where possible, the Java SDK uses native types from the language and uses primit
 - `double` (or `java.lang.Double`)
 - `boolean` (or `java.lang.Boolean`)
 
-
 ### Unlimited-precision numerics
 
 Using high-precision decimal or integer types is crucial in certain applications, such as in code that manipulates monetary amounts and in situations where overflow, underflow, or truncation caused by precision loss can lead to significant incidents.
 
 To mark a field as an unlimited-precision integer, you can use either an integer:
 
 ```yaml
-  type: integer
-  format: bigint
-``` 
+type: integer
+format: bigint
+```
 
 Or a string:
 
 ```yaml
-  type: string
-  format: bigint
+type: string
+format: bigint
 ```
 
 The above types are mapped to `java.math.BigInteger` in the generated SDK. Object builders have convenient overloads that allow for passing integer values directly without wrapping them in `BigInteger`.
 
 Similarly, for an unlimited-precision decimal, you can use either a number:
 
 ```yaml
-  type: number
-  format: decimal
+type: number
+format: decimal
 ```
 
-Or a string: 
+Or a string:
 
 ```yaml
-  type: string
-  format: decimal
+type: string
+format: decimal
 ```
+
 The above types are mapped to `java.math.BigDecimal` in the generated SDK and object builders have convenient overloads that allow passing float and double values directly without wrapping them in `BigDecimal`.
 
 **Note:** SDKs in other languages may choose to map to native high-precision types rather than unlimited-precision types. Check the documentation of the language you are interested in.
 
 ### Union types
 
-Support for polymorphic types is critical to most production applications. In OpenAPI, these types are defined using the `oneOf` keyword. 
+Support for polymorphic types is critical to most production applications. In OpenAPI, these types are defined using the `oneOf` keyword.
 
 #### Non-discriminated `oneOf`
 
@@ -196,10 +196,10 @@ The subtypes of a non-discriminated `oneOf` type may be objects or primitives, s
 Consider this OpenAPI fragment:
 
 ```yaml
-    Pet:
-      oneOf:
-      - $ref: "#/components/schemas/Cat"
-      - $ref: "#/components/schemas/Dog"
+Pet:
+  oneOf:
+    - $ref: "#/components/schemas/Cat"
+    - $ref: "#/components/schemas/Dog"
 ```
 
 Here's how a `Pet` is created in Java code:
@@ -209,8 +209,8 @@ Cat cat = ...;
 Dog dog = ...;
 
 // Pet.of only accepts Cat or Dog types, and throws if passed null.
-Pet pet = Pet.of(cat); 
-``` 
+Pet pet = Pet.of(cat);
+```
 
 Here is how a `Pet` is inspected:
 
@@ -245,19 +245,19 @@ if (pet.value() instanceof Cat cat) {
 In some circumstances, the `of` static factory method of a `oneOf` class may need to be differentiated by a suffix to avoid type erasure. For example, you would need to use a suffix to differentiate the two array subtypes in the following fragment:
 
 ```yaml
-    Info:
-      oneOf:
-      - type: array
-        items: 
-          type: integer
-        x-speakeasy-name-override: counts
-      - type: array
-        items: 
-          type: string
-        x-speakeasy-name-override: descriptions
+Info:
+  oneOf:
+    - type: array
+      items:
+        type: integer
+      x-speakeasy-name-override: counts
+    - type: array
+      items:
+        type: string
+      x-speakeasy-name-override: descriptions
 ```
 
-Without accounting for this scenario, the static factory methods `Info.of(List<Long>)` and `Info.of(List<String>)` would conflict due to generic type erasure by the Java compiler and cause a compile error in the generated code. Code generation detects this scenario and adds an `of` method suffix. For the fragment above, the generated static factory methods are the following: 
+Without accounting for this scenario, the static factory methods `Info.of(List<Long>)` and `Info.of(List<String>)` would conflict due to generic type erasure by the Java compiler and cause a compile error in the generated code. Code generation detects this scenario and adds an `of` method suffix. For the fragment above, the generated static factory methods are the following:
 
 - `ofCounts(List<Long>)`
 - `ofDescriptions(List<String>)`
@@ -276,15 +276,15 @@ The subtypes of a discriminated `oneOf` type must be objects, so an interface-ba
 Consider this OpenAPI fragment:
 
 ```yaml
-    Pet:
-      oneOf:
-      - $ref: "#/components/schemas/Cat"
-      - $ref: "#/components/schemas/Dog"
-      discriminator:
-        propertyName: petType
-        mapping: 
-          cat: '#/components/schemas/Cat'
-          dog: '#/components/schemas/Dog'
+Pet:
+  oneOf:
+    - $ref: "#/components/schemas/Cat"
+    - $ref: "#/components/schemas/Dog"
+  discriminator:
+    propertyName: petType
+    mapping:
+      cat: "#/components/schemas/Cat"
+      dog: "#/components/schemas/Dog"
 ```
 
 Here's how a `Pet` is created in Java code:
@@ -294,7 +294,7 @@ Pet cat = Cat.builder().name("Moggie").build();
 Pet dog = Dog.builder().name("Fido").build();
 ```
 
-`Pet` is a Java interface with a single `petType()` method, and `Cat` and `Dog` both implement that interface. 
+`Pet` is a Java interface with a single `petType()` method, and `Cat` and `Dog` both implement that interface.
 
 The `discriminator` property should be marked as required in the `oneOf` subtypes. Considering the discriminator has a constant value in each `oneOf` subtype, it also makes sense to use a Singleton `enum` or a `const` for the `discriminator` property type.
 
@@ -390,15 +390,15 @@ Be aware that migrating a closed enum to an open enum may bring about compile er
 
 ## Parameters
 
-If parameters are defined in the OpenAPI document, Speakeasy will generate methods with parameters as part of the method call itself rather than as part of a separate request object. 
+If parameters are defined in the OpenAPI document, Speakeasy will generate methods with parameters as part of the method call itself rather than as part of a separate request object.
 
 The number of parameters defined should not exceed the `maxMethodParams` value configured in the `gen.yaml` file. If they do or the `maxMethodParams` value is absent or set to `0`, all generated methods require a single request object that contains all the parameters that may be used to call an endpoint in the API.
 
 ## Default values
 
-The `default` keyword in the OpenAPI specification allows a user to omit a field or parameter and it will be set with a given default value. 
+The `default` keyword in the OpenAPI specification allows a user to omit a field or parameter and it will be set with a given default value.
 
-Default values are represented in the Java SDK with `java.util.Optional` wrappers. Passing `Optional.empty()`, or if you're using a builder, not setting the field or parameter, will mean that the default value in the OpenAPI document is used. 
+Default values are represented in the Java SDK with `java.util.Optional` wrappers. Passing `Optional.empty()`, or if you're using a builder, not setting the field or parameter, will mean that the default value in the OpenAPI document is used.
 
 Bear in mind that it's lazy-loaded (only loaded once) and that if the default value is not valid for the given type, an `IllegalArgumentException` will be thrown. For example, if `default: abc` is specified for `type: integer`, the exception is thrown.
 
@@ -416,21 +416,45 @@ The `const` keyword in the OpenAPI specification ensures that a field is essenti
 To handle errors in the Java SDK, you need to check the status code of the response. If it is an error response, the `error` field of the response will contain the decoded error value.
 
 <Callout title="Coming Soon" type="info">
-Support for throwing unsuccessful status codes as exceptions is coming soon.
+  Support for throwing unsuccessful status codes as exceptions is coming soon.
 </Callout>
 
 ## Pagination and `java.util.Stream`
 
-Enabling pagination for an operation in your API is described [here](/docs/customize/runtime/pagination). 
+Enabling pagination for an operation in your API is described [here](/docs/customize/runtime/pagination).
 
-If pagination is enabled for an operation, you have the option to run `.call()`, `.callAsStream()`, or `.callAsStreamUnwrapped()` when using the operation builder. 
+If pagination is enabled for an operation, you have the option to run `.call()`, `.callAsIterable()`, `.callAsStream()`, or `.callAsStreamUnwrapped()` when using the operation builder.
 
-- The `.call()` method will return the first page, and you will have to repeatedly check for the existence of another page and retrieve it. 
+- The `.call()` method will return the first page, and you will have to repeatedly check for the existence of another page and retrieve it.
+- The `.callAsIterable()` method returns an `Iterable<>` that can be used with for-each iteration style. Page retrieval is handled automatically as the iteration progresses.
 - The `callAsStream()` method returns a `java.util.Stream` of the pages, allowing you to use the convenient `java.util.Stream` API. Retrieving more pages when required and available is handled automatically.
 - The `callAsStreamUnwrapped()` method returns a `java.util.Stream` of the concatenated items in the lists on each page. Concatenation and page retrieval are handled automatically.
 
+Below is an example of `callAsIterable()`:
+
+```java
+SDK sdk = SDK.builder() ... ;
+
+var iterable = sdk.searchDocuments()
+    .contains("simple")   // parameter
+    .minSize(200)         // parameter
+    .maxSize(400)         // parameter
+    .callAsIterable();    // returns Iterable<DocumentsPageResponse>
+
+for (var response : iterable) {
+    List<Document> documents = response.res()
+        .map(page -> page.documents())
+        .orElse(Collections.emptyList());
+    for (Document document : documents) {
+        if ("fiction".equals(document.category())) {
+            System.out.println(document.name());
+        }
+    }
+}
+```
+
 Below is an example of `callAsStream()`:
- 
+
 ```java
 SDK sdk = SDK.builder() ... ;
 
@@ -456,19 +480,17 @@ sdk.searchDocuments()    // builder for the request
    .contains("simple")   // parameter
    .minSize(200)         // parameter
    .maxSize(400)         // parameter
-   .callAsStreamUnwrapped() 
+   .callAsStreamUnwrapped()
    // we are now dealing with a Stream<Document>
    .filter(document -> "fiction".equals(document.category())
    .limit(200) // no more than 200 documents
    .map(document -> document.name())
    .forEach(System.out::println);
 ```
 
-The `callAsStream` and `callAsStreamUnwrapped` methods throw an exception if a response page has a status code of 300 or higher. If you require a different behavior, use the `call` method to manually retrieve each page.
-
 ## Server-sent events
 
-General Speakeasy support for server-sent events (SSE) is described [here](/docs/customize-sdks/server-sent-events). 
+General Speakeasy support for server-sent events (SSE) is described [here](/docs/customize-sdks/server-sent-events).
 
 When an operation response has a content type of `text/event-stream`, the generated response class will have an `events()` method.
 
@@ -503,7 +525,7 @@ events.forEach(event -> processEvent(event));
 
 ## User agent strings
 
-The Java SDK will include a [user agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) string in all requests that can be used to track SDK usage among broader API usage. The format is as follows: 
+The Java SDK will include a [user agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) string in all requests that can be used to track SDK usage among broader API usage. The format is as follows:
 
 ```stmpl
 speakeasy-sdk/java {{SDKVersion}} {{GenVersion}} {{DocVersion}} {{groupId.artifactId}}
