Skip to content

Commit ea6afdb

Browse files
box-sdk-buildbox-sdk-build
committed
docs: Migration guide for Python and Java (box/box-codegen#816)
1 parent 3c0ad2a commit ea6afdb

File tree

4 files changed

+150
-2
lines changed

4 files changed

+150
-2
lines changed

‎.codegen.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
{ "engineHash": "c0b8367", "specHash": "ec8720b", "version": "0.1.0" }
1+
{ "engineHash": "aa448e3", "specHash": "ec8720b", "version": "0.1.0" }

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ Browse the [docs](docs/README.md) or see [API Reference](https://developer.box.c
9090

9191
# Upgrades
9292

93-
The SDK is updated regularly to include new features, enhancements, and bug fixes. If you are upgrading from manual SDK to this new generated SDK checkout the [migration guide](MIGRATION_GUIDE.md) and [changelog](CHANGELOG.md) for more information.
93+
The SDK is updated regularly to include new features, enhancements, and bug fixes. If you are upgrading from manual SDK to this new generated SDK checkout the [migration guide](migration-guides/from-v4-to-v10.md) and [changelog](CHANGELOG.md) for more information.
9494

9595
# Integration Tests
9696

‎migration-guides/from-box-java-sdk-gen-v0-to-box-java-sdk-v10.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# Migration guide from beta release (v0.8.0) of the `box-java-sdk-gen` to the v10 version of the `box-java-sdk`
2+
3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
6+
- [Installation](#installation)
7+
- [How to migrate](#how-to-migrate)
8+
- [Maven](#maven)
9+
- [Gradle](#gradle)
10+
- [Union classes name changes](#union-classes-name-changes)
11+
- [How to migrate](#how-to-migrate-1)
12+
- [Removed unused models from schemas namespace](#removed-unused-models-from-schemas-namespace)
13+
- [How to migrate](#how-to-migrate-2)
14+
15+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
16+
17+
## Installation
18+
19+
In order to start using v10 version of the Box Java SDK, you need to change the dependency in your project.
20+
The artifact name has changed from `com.box:box-java-sdk-gen` to `com.box:box-java-sdk`.
21+
You also need to set the version to `10.0.0` or higher. You can find the latest version on [Maven Central](https://search.maven.org/artifact/com.box/box-java-sdk).
22+
23+
### How to migrate
24+
25+
#### Maven
26+
27+
To start using v10 version of Box Java SDK in your Maven project replace the dependency in your `pom.xml` file.
28+
29+
**Old (`box-java-sdk-gen-v0`)**
30+
31+
```xml
32+
<dependency>
33+
<groupId>com.box</groupId>
34+
<artifactId>box-java-sdk-gen</artifactId>
35+
<version>0.8.0</version>
36+
</dependency>
37+
```
38+
39+
**New (`box-java-sdk-v10`)**
40+
41+
```xml
42+
<dependency>
43+
<groupId>com.box</groupId>
44+
<artifactId>box-java-sdk</artifactId>
45+
<version>10.0.0</version>
46+
</dependency>
47+
```
48+
49+
#### Gradle
50+
51+
To start using v10 version of Box Java SDK in your Gradle project replace the dependency in your `build.gradle` file.
52+
53+
**Old (`box-java-sdk-gen-v0`)**
54+
55+
```groovy
56+
implementation 'com.box:box-java-sdk-gen:0.8.0'
57+
```
58+
59+
**New (`box-java-sdk-v10`)**
60+
61+
```groovy
62+
implementation 'com.box:box-java-sdk:10.0.0'
63+
```
64+
65+
## Union classes name changes
66+
67+
In the beta version of the `box-java-sdk-gen` our `OneOf` class names (representing unions from the OpenAPI specification)
68+
were fully auto-generated based on the included variants. This often resulted in overly long names that were difficult
69+
to work with in tools like Git. For example: `MetadataFieldFilterDateRangeOrMetadataFieldFilterFloatRangeOrArrayOfStringOrNumberOrString`.
70+
Additionally, every time the new variant was added to the `OneOf`, the class name itself changed.
71+
Starting in v10, the names of `OneOf` classes are defined directly in the specification. This ensures that they are meaningful, short, and stable over time.
72+
73+
### How to migrate
74+
75+
If your code references any of the renamed classes, replace the old name with the new one.
76+
If you were not explicitly using the type names, no changes are needed, since only the class names changed and their behavior remains the same.
77+
78+
List of changed `OneOf` classes and types associated with them:
79+
80+
| Old name | New name |
81+
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
82+
| AiAgentAskOrAiAgentExtractOrAiAgentExtractStructuredOrAiAgentTextGen | AiAgent |
83+
| AiAgentAskOrAiAgentReference | AiAskAgent |
84+
| AiAgentExtractOrAiAgentReference | AiExtractAgent |
85+
| AiAgentExtractStructuredOrAiAgentReference | AiExtractStructuredAgent |
86+
| AiAgentReferenceOrAiAgentTextGen | AiTextGenAgent |
87+
| AppItemEventSourceOrEventSourceOrFileOrFolderOrGenericSourceOrUser | EventSourceResource |
88+
| FileBaseOrFolderBaseOrWebLinkBase | AppItemAssociatedItem |
89+
| FileFullOrFolderFull | MetadataQueryResultItem |
90+
| FileFullOrFolderFullOrWebLink | SearchResultWithSharedLinkItem/RecentItemResource/SearchResultItem |
91+
| FileFullOrFolderMiniOrWebLink | Item |
92+
| FileMiniOrFolderMini | Resource |
93+
| FileOrFolderOrWebLink | LegalHoldPolicyAssignedItem/CollaborationItem |
94+
| FileOrFolderScope | ResourceScope |
95+
| FileReferenceOrFolderReferenceOrWeblinkReferenceV2025R0 | HubItemReferenceV2025R0 |
96+
| GroupMiniOrUserCollaborations | CollaborationAccessGrantee |
97+
| IntegrationMappingPartnerItemSlackUnion | IntegrationMappingPartnerItemSlack |
98+
| IntegrationMappingPartnerItemTeamsUnion | IntegrationMappingPartnerItemTeams |
99+
| KeywordSkillCardOrStatusSkillCardOrTimelineSkillCardOrTranscriptSkillCard | SkillCard |
100+
| MetadataFieldFilterDateRangeOrMetadataFieldFilterFloatRangeOrArrayOfStringOrNumberOrString | MetadataFilterValue |
101+
| SearchResultsOrSearchResultsWithSharedLinks | SearchResultsResponse |
102+
103+
Some classes were split into multiple ones depending on context.
104+
105+
Manager functions affected by these changes:
106+
107+
| Function | Old return type | New return type |
108+
| -------------------------------------- | -------------------------------------------------------------------- | --------------------- |
109+
| AiManager.getAiAgentDefaultConfig(...) | AiAgentAskOrAiAgentExtractOrAiAgentExtractStructuredOrAiAgentTextGen | AiAgent |
110+
| SearchManager.searchForContent(...) | SearchResultsOrSearchResultsWithSharedLinks | SearchResultsResponse |
111+
112+
## Removed unused models from schemas namespace
113+
114+
Several unused types (classes and enums) have been removed from the schemas because they were not used by any SDK functions or by the Box API.
115+
116+
### How to migrate
117+
118+
Here is the full list of removed types:
119+
120+
| Removed classes/enums |
121+
| ------------------------------------------ |
122+
| FileOrFolder |
123+
| HubActionV2025R0 |
124+
| MetadataQueryIndex |
125+
| MetadataQueryIndexFieldsField |
126+
| MetadataQueryIndexFieldsSortDirectionField |
127+
| MetadataQueryIndexStatusField |
128+
| RetentionPolicyAssignmentBase |
129+
| RetentionPolicyAssignmentBaseTypeField |
130+
| SkillInvocation |
131+
| SkillInvocationEnterpriseField |
132+
| SkillInvocationEnterpriseTypeField |
133+
| SkillInvocationSkillField |
134+
| SkillInvocationSkillTypeField |
135+
| SkillInvocationStatusField |
136+
| SkillInvocationStatusStateField |
137+
| SkillInvocationTokenField |
138+
| SkillInvocationTokenReadField |
139+
| SkillInvocationTokenReadTokenTypeField |
140+
| SkillInvocationTokenWriteField |
141+
| SkillInvocationTokenWriteTokenTypeField |
142+
| SkillInvocationTypeField |
143+
| WebhookInvocation |
144+
| WebhookInvocationTriggerField |
145+
| WebhookInvocationTypeField |
146+
| WorkflowFull |
147+
148+
If your code references any of these types, remove those references.

migration-guide.md renamed to migration-guides/from-v4-to-v10.md

File renamed without changes.

0 commit comments

Comments
 (0)