Skip to content

Commit ce30a3c

Browse files
stainless-app[bot]stainless-app[bot]
committed
docs: clarify forwards compat behavior
1 parent 417cab1 commit ce30a3c

37 files changed

Lines changed: 1458 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -553,7 +553,9 @@ In rare cases, the API may return a response that doesn't match the expected typ
553553

554554
By default, the SDK will not throw an exception in this case. It will throw [`OnebusawaySdkInvalidDataException`](onebusaway-sdk-java-core/src/main/kotlin/org/onebusaway/errors/OnebusawaySdkInvalidDataException.kt) only if you directly access the property.
555555

556-
If you would prefer to check that the response is completely well-typed upfront, then either call `validate()`:
556+
Validating the response is _not_ forwards compatible with new types from the API for existing fields.
557+
558+
If you would still prefer to check that the response is completely well-typed upfront, then either call `validate()`:
557559

558560
```java
559561
import org.onebusaway.models.currenttime.CurrentTimeRetrieveResponse;

‎onebusaway-sdk-java-client-okhttp/src/main/kotlin/org/onebusaway/client/okhttp/OnebusawaySdkOkHttpClient.kt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -217,6 +217,9 @@ class OnebusawaySdkOkHttpClient private constructor() {
217217
/**
218218
* Whether to call `validate` on every response before returning it.
219219
*
220+
* Setting this to `true` is _not_ forwards compatible with new types from the API for
221+
* existing fields.
222+
*
220223
* Defaults to false, which means the shape of the response will not be validated upfront.
221224
* Instead, validation will only occur for the parts of the response that are accessed.
222225
*/

‎onebusaway-sdk-java-client-okhttp/src/main/kotlin/org/onebusaway/client/okhttp/OnebusawaySdkOkHttpClientAsync.kt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -217,6 +217,9 @@ class OnebusawaySdkOkHttpClientAsync private constructor() {
217217
/**
218218
* Whether to call `validate` on every response before returning it.
219219
*
220+
* Setting this to `true` is _not_ forwards compatible with new types from the API for
221+
* existing fields.
222+
*
220223
* Defaults to false, which means the shape of the response will not be validated upfront.
221224
* Instead, validation will only occur for the parts of the response that are accessed.
222225
*/

‎onebusaway-sdk-java-core/src/main/kotlin/org/onebusaway/core/ClientOptions.kt‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,9 @@ private constructor(
6666
/**
6767
* Whether to call `validate` on every response before returning it.
6868
*
69+
* Setting this to `true` is _not_ forwards compatible with new types from the API for existing
70+
* fields.
71+
*
6972
* Defaults to false, which means the shape of the response will not be validated upfront.
7073
* Instead, validation will only occur for the parts of the response that are accessed.
7174
*/
@@ -229,6 +232,9 @@ private constructor(
229232
/**
230233
* Whether to call `validate` on every response before returning it.
231234
*
235+
* Setting this to `true` is _not_ forwards compatible with new types from the API for
236+
* existing fields.
237+
*
232238
* Defaults to false, which means the shape of the response will not be validated upfront.
233239
* Instead, validation will only occur for the parts of the response that are accessed.
234240
*/

‎onebusaway-sdk-java-core/src/main/kotlin/org/onebusaway/core/RequestOptions.kt‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,15 @@ class RequestOptions private constructor(val responseValidation: Boolean?, val t
3333
private var responseValidation: Boolean? = null
3434
private var timeout: Timeout? = null
3535

36+
/**
37+
* Whether to call `validate` on the response before returning it.
38+
*
39+
* Setting this to `true` is _not_ forwards compatible with new types from the API for
40+
* existing fields.
41+
*
42+
* Defaults to false, which means the shape of the response will not be validated upfront.
43+
* Instead, validation will only occur for the parts of the response that are accessed.
44+
*/
3645
fun responseValidation(responseValidation: Boolean) = apply {
3746
this.responseValidation = responseValidation
3847
}

‎onebusaway-sdk-java-core/src/main/kotlin/org/onebusaway/models/References.kt‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -377,6 +377,14 @@ private constructor(
377377

378378
private var validated: Boolean = false
379379

380+
/**
381+
* Validates that the types of all values in this object match their expected types recursively.
382+
*
383+
* This method is _not_ forwards compatible with new types from the API for existing fields.
384+
*
385+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't match its
386+
* expected type.
387+
*/
380388
fun validate(): References = apply {
381389
if (validated) {
382390
return@apply
@@ -819,6 +827,15 @@ private constructor(
819827

820828
private var validated: Boolean = false
821829

830+
/**
831+
* Validates that the types of all values in this object match their expected types
832+
* recursively.
833+
*
834+
* This method is _not_ forwards compatible with new types from the API for existing fields.
835+
*
836+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't match
837+
* its expected type.
838+
*/
822839
fun validate(): Agency = apply {
823840
if (validated) {
824841
return@apply
@@ -1318,6 +1335,15 @@ private constructor(
13181335

13191336
private var validated: Boolean = false
13201337

1338+
/**
1339+
* Validates that the types of all values in this object match their expected types
1340+
* recursively.
1341+
*
1342+
* This method is _not_ forwards compatible with new types from the API for existing fields.
1343+
*
1344+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't match
1345+
* its expected type.
1346+
*/
13211347
fun validate(): Route = apply {
13221348
if (validated) {
13231349
return@apply
@@ -1971,6 +1997,15 @@ private constructor(
19711997

19721998
private var validated: Boolean = false
19731999

2000+
/**
2001+
* Validates that the types of all values in this object match their expected types
2002+
* recursively.
2003+
*
2004+
* This method is _not_ forwards compatible with new types from the API for existing fields.
2005+
*
2006+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't match
2007+
* its expected type.
2008+
*/
19742009
fun validate(): Situation = apply {
19752010
if (validated) {
19762011
return@apply
@@ -2153,6 +2188,16 @@ private constructor(
21532188

21542189
private var validated: Boolean = false
21552190

2191+
/**
2192+
* Validates that the types of all values in this object match their expected types
2193+
* recursively.
2194+
*
2195+
* This method is _not_ forwards compatible with new types from the API for existing
2196+
* fields.
2197+
*
2198+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't
2199+
* match its expected type.
2200+
*/
21562201
fun validate(): ActiveWindow = apply {
21572202
if (validated) {
21582203
return@apply
@@ -2487,6 +2532,16 @@ private constructor(
24872532

24882533
private var validated: Boolean = false
24892534

2535+
/**
2536+
* Validates that the types of all values in this object match their expected types
2537+
* recursively.
2538+
*
2539+
* This method is _not_ forwards compatible with new types from the API for existing
2540+
* fields.
2541+
*
2542+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't
2543+
* match its expected type.
2544+
*/
24902545
fun validate(): AllAffect = apply {
24912546
if (validated) {
24922547
return@apply
@@ -2701,6 +2756,16 @@ private constructor(
27012756

27022757
private var validated: Boolean = false
27032758

2759+
/**
2760+
* Validates that the types of all values in this object match their expected types
2761+
* recursively.
2762+
*
2763+
* This method is _not_ forwards compatible with new types from the API for existing
2764+
* fields.
2765+
*
2766+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't
2767+
* match its expected type.
2768+
*/
27042769
fun validate(): Consequence = apply {
27052770
if (validated) {
27062771
return@apply
@@ -2894,6 +2959,16 @@ private constructor(
28942959

28952960
private var validated: Boolean = false
28962961

2962+
/**
2963+
* Validates that the types of all values in this object match their expected types
2964+
* recursively.
2965+
*
2966+
* This method is _not_ forwards compatible with new types from the API for existing
2967+
* fields.
2968+
*
2969+
* @throws OnebusawaySdkInvalidDataException if any value type in this object
2970+
* doesn't match its expected type.
2971+
*/
28972972
fun validate(): ConditionDetails = apply {
28982973
if (validated) {
28992974
return@apply
@@ -3109,6 +3184,16 @@ private constructor(
31093184

31103185
private var validated: Boolean = false
31113186

3187+
/**
3188+
* Validates that the types of all values in this object match their expected
3189+
* types recursively.
3190+
*
3191+
* This method is _not_ forwards compatible with new types from the API for
3192+
* existing fields.
3193+
*
3194+
* @throws OnebusawaySdkInvalidDataException if any value type in this object
3195+
* doesn't match its expected type.
3196+
*/
31123197
fun validate(): DiversionPath = apply {
31133198
if (validated) {
31143199
return@apply
@@ -3337,6 +3422,16 @@ private constructor(
33373422

33383423
private var validated: Boolean = false
33393424

3425+
/**
3426+
* Validates that the types of all values in this object match their expected types
3427+
* recursively.
3428+
*
3429+
* This method is _not_ forwards compatible with new types from the API for existing
3430+
* fields.
3431+
*
3432+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't
3433+
* match its expected type.
3434+
*/
33403435
fun validate(): Description = apply {
33413436
if (validated) {
33423437
return@apply
@@ -3539,6 +3634,16 @@ private constructor(
35393634

35403635
private var validated: Boolean = false
35413636

3637+
/**
3638+
* Validates that the types of all values in this object match their expected types
3639+
* recursively.
3640+
*
3641+
* This method is _not_ forwards compatible with new types from the API for existing
3642+
* fields.
3643+
*
3644+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't
3645+
* match its expected type.
3646+
*/
35423647
fun validate(): PublicationWindow = apply {
35433648
if (validated) {
35443649
return@apply
@@ -3718,6 +3823,16 @@ private constructor(
37183823

37193824
private var validated: Boolean = false
37203825

3826+
/**
3827+
* Validates that the types of all values in this object match their expected types
3828+
* recursively.
3829+
*
3830+
* This method is _not_ forwards compatible with new types from the API for existing
3831+
* fields.
3832+
*
3833+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't
3834+
* match its expected type.
3835+
*/
37213836
fun validate(): Summary = apply {
37223837
if (validated) {
37233838
return@apply
@@ -3897,6 +4012,16 @@ private constructor(
38974012

38984013
private var validated: Boolean = false
38994014

4015+
/**
4016+
* Validates that the types of all values in this object match their expected types
4017+
* recursively.
4018+
*
4019+
* This method is _not_ forwards compatible with new types from the API for existing
4020+
* fields.
4021+
*
4022+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't
4023+
* match its expected type.
4024+
*/
39004025
fun validate(): Url = apply {
39014026
if (validated) {
39024027
return@apply
@@ -4475,6 +4600,15 @@ private constructor(
44754600

44764601
private var validated: Boolean = false
44774602

4603+
/**
4604+
* Validates that the types of all values in this object match their expected types
4605+
* recursively.
4606+
*
4607+
* This method is _not_ forwards compatible with new types from the API for existing fields.
4608+
*
4609+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't match
4610+
* its expected type.
4611+
*/
44784612
fun validate(): Stop = apply {
44794613
if (validated) {
44804614
return@apply
@@ -4853,6 +4987,15 @@ private constructor(
48534987

48544988
private var validated: Boolean = false
48554989

4990+
/**
4991+
* Validates that the types of all values in this object match their expected types
4992+
* recursively.
4993+
*
4994+
* This method is _not_ forwards compatible with new types from the API for existing fields.
4995+
*
4996+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't match
4997+
* its expected type.
4998+
*/
48564999
fun validate(): StopTime = apply {
48575000
if (validated) {
48585001
return@apply
@@ -5379,6 +5522,15 @@ private constructor(
53795522

53805523
private var validated: Boolean = false
53815524

5525+
/**
5526+
* Validates that the types of all values in this object match their expected types
5527+
* recursively.
5528+
*
5529+
* This method is _not_ forwards compatible with new types from the API for existing fields.
5530+
*
5531+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't match
5532+
* its expected type.
5533+
*/
53825534
fun validate(): Trip = apply {
53835535
if (validated) {
53845536
return@apply

‎onebusaway-sdk-java-core/src/main/kotlin/org/onebusaway/models/ResponseWrapper.kt‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -220,6 +220,14 @@ private constructor(
220220

221221
private var validated: Boolean = false
222222

223+
/**
224+
* Validates that the types of all values in this object match their expected types recursively.
225+
*
226+
* This method is _not_ forwards compatible with new types from the API for existing fields.
227+
*
228+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't match its
229+
* expected type.
230+
*/
223231
fun validate(): ResponseWrapper = apply {
224232
if (validated) {
225233
return@apply

‎onebusaway-sdk-java-core/src/main/kotlin/org/onebusaway/models/agencieswithcoverage/AgenciesWithCoverageListResponse.kt‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -267,6 +267,14 @@ private constructor(
267267

268268
private var validated: Boolean = false
269269

270+
/**
271+
* Validates that the types of all values in this object match their expected types recursively.
272+
*
273+
* This method is _not_ forwards compatible with new types from the API for existing fields.
274+
*
275+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't match its
276+
* expected type.
277+
*/
270278
fun validate(): AgenciesWithCoverageListResponse = apply {
271279
if (validated) {
272280
return@apply
@@ -505,6 +513,15 @@ private constructor(
505513

506514
private var validated: Boolean = false
507515

516+
/**
517+
* Validates that the types of all values in this object match their expected types
518+
* recursively.
519+
*
520+
* This method is _not_ forwards compatible with new types from the API for existing fields.
521+
*
522+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't match
523+
* its expected type.
524+
*/
508525
fun validate(): Data = apply {
509526
if (validated) {
510527
return@apply
@@ -788,6 +805,16 @@ private constructor(
788805

789806
private var validated: Boolean = false
790807

808+
/**
809+
* Validates that the types of all values in this object match their expected types
810+
* recursively.
811+
*
812+
* This method is _not_ forwards compatible with new types from the API for existing
813+
* fields.
814+
*
815+
* @throws OnebusawaySdkInvalidDataException if any value type in this object doesn't
816+
* match its expected type.
817+
*/
791818
fun validate(): List = apply {
792819
if (validated) {
793820
return@apply

0 commit comments

Comments
 (0)