DOCSEARCHbyAlgolia
Submit Docs

Box Java SDK

repository·main·Indexed 41 days ago

https://github.com/box/box-java-sdk

A programmatic interface for interacting with the Box Content Cloud. The SDK features two architectural paths: the legacy com.box.sdk package and the new generated com.box.sdkgen package (v10+). It provides comprehensive coverage for core content management, collaboration, security, and advanced AI features such as text generation, metadata extraction, and AI agent management via AiStudioManager. Supports multiple authentication methods including OAuth 2.0, JWT, and Developer Tokens.

Tokens
85.1K
Snippets
387
Records
434
Agent score
51%

What's inside Box Java SDK

  1. Explore Box API functionality by topic

    main

    The Box Java SDK provides comprehensive coverage for nearly all Box API features. You can find specific implementation guides and usage examples for various domains, including:

    • Core Content Management: Files, Folders, Fileversions, Uploads, Downloads, and Trash management.
    • Collaboration: Collaborations, Sharedlinks, Groups, and Users.
    • Metadata & Classification: Filemetadata, Foldermetadata, Classifications, and Metadatataxonomies.
    • Security & Compliance: Legalholdpolicies, Retentionpolicies, Shieldinformationbarriers, and Storagepolicies.
    • Advanced Features: Search, Query, Webhooks, Workflows, AI, and Signrequests.

    Refer to the specific topic documentation to learn how to interact with these individual API resources.

  2. Manage metadata taxonomies with MetadataTaxonomiesManager

    main
    The MetadataTaxonomiesManager provides methods to manage metadata taxonomies within a specific namespace. Taxonomies can be created, retrieved, updated, or deleted. These taxonomies serve as the foundation for metadata templates used to categorize content.

  3. Manage webhooks with WebhooksManager

    main

    The WebhooksManager provides methods to manage Box webhooks, including listing, creating, retrieving, updating, and deleting them.

    Important Note on Visibility: The getWebhooks method only returns webhooks applied to files or folders owned by the authenticated user. An admin cannot see webhooks created by a service account unless the admin has explicit access to those specific folders/files.

  5. How to authenticate as a specific user using JWT in com.box.sdkgen

    main

    To switch from a Service Account to a specific user context in com.box.sdkgen, call withUserSubject(String userId, TokenStorage tokenStorage) on your existing BoxJWTAuth instance. This returns a new BoxJWTAuth instance that performs the authentication in the scope of the specified user on the first API call. You can then use this new auth instance to create a new BoxClient.

    BoxJWTAuth userAuth = auth.withUserSubject("USER_ID");
BoxClient userClient = new BoxClient(userAuth);

  6. Manage SDK upgrades and deprecations

    main

    The SDK uses deprecation warnings to manage the transition between versions without immediate breakage:

    1. Introduction: Deprecations are introduced in minor releases. They do not change existing behavior but emit warnings providing guidance on alternatives and the version where the deprecation will be enforced.
    2. Enforcement: Deprecations are only enforced in major releases.
      • Example: If a behavior is deprecated in version 1.2.0, it will continue to function (with a warning) throughout the entire 1.x series. The behavior will only change/be removed in the 2.x.x series.
    3. End of Life (EOL): Once a major version reaches EOL, it no longer receives new features, bug fixes, or security patches. Applications using EOL versions will continue to run, but you should plan an upgrade to a supported major version.

  7. How the Manager approach works in com.box.sdkgen

    main

    In the old com.box.sdk, API actions were performed directly on resource objects (e.g., BoxUser). In the new com.box.sdkgen, API methods are grouped into dedicated Manager classes accessible via the BoxClient object.

    Resource objects returned by the SDK (like UserFull) are now data classes and do not contain methods to perform API actions. To perform operations, you must use the corresponding manager (e.g., client.users).

    Comparison

    Old (com.box.sdk) pattern:

    1. Instantiate a resource object with an ID.
    2. Call methods on that object to perform actions.

    New (com.box.sdkgen) pattern:

    1. Access the manager via the client (e.g., client.users).
    2. Call the manager's method, passing the resource ID as an argument if required.

    Example: Getting and Updating a User

    // Getting a user
UserFull user = client.users.getUsersById("12345");

// Creating a user
CreateUserRequestBody requestBody = new CreateUserRequestBody.Builder("John Doe").build();
UserFull newUser = client.users.createUser(requestBody);

// Updating a user (using the ID from the data class)
UpdateUserByIdRequestBody updateBody = new UpdateUserByIdRequestBody.Builder().name("Mary").build();
UserFull updatedUser = client.users.updateUserById(user.getId(), updateBody);

  8. Use both com.box.sdk and com.box.sdkgen in v5

    main

    In version 5, you can use both the legacy com.box.sdk package and the new com.box.sdkgen package simultaneously. To avoid naming conflicts if both packages contain classes with the same name, use fully qualified names.

    Import classes from the specific package required for the functionality you are implementing.

    import com.box.sdk.BoxConfig;
import com.box.sdk.BoxDeveloperEditionAPIConnection;
import com.box.sdk.BoxFolder;
import com.box.sdkgen.box.jwtauth.BoxJWTAuth;
import com.box.sdkgen.box.jwtauth.JWTConfig;
import com.box.sdkgen.client.BoxClient;
import com.box.sdkgen.managers.folders.UpdateFolderByIdRequestBody;
import com.box.sdkgen.schemas.folder.Folder;

import java.io.FileReader;
import java.io.Reader;

public class Main {
  public static void main(String[] args) throws Exception {

    // Using legacy com.box.sdk
    Reader reader = new FileReader("src/example/config/config.json");
    BoxConfig boxConfig = BoxConfig.readFrom(reader);
    BoxDeveloperEditionAPIConnection api = BoxDeveloperEditionAPIConnection.getAppEnterpriseConnection(boxConfig);
    BoxFolder rootFolder = new BoxFolder(api, "0");
    BoxFolder.Info subfolder = rootFolder.createFolder("My Subfolder");

    // Using new com.box.sdkgen
    JWTConfig config = JWTConfig.fromConfigFile("src/example/config/config.json");
    BoxJWTAuth auth = new BoxJWTAuth(config);
    BoxClient client = new BoxClient(auth);

    Folder updatedFolder = client.getFolders().updateFolderById(
            subfolder.getID(),
            new UpdateFolderByIdRequestBody.Builder().name("My Updated Subfolder").build()
    );
    System.out.println("Created folder with ID " + subfolder.getID() + " has been updated to " + updatedFolder.getName());
  }
}

  9. Understand the Box Java SDK versioning scheme

    main

    The Box Java SDK uses a modified version of Semantic Versioning (MAJOR.MINOR.PATCH). To avoid breaking changes, it is strongly recommended to pin at least the major version in your dependency configuration.

    • PATCH (x.y.Z): Incremented for backwards-compatible bug fixes. These are generally safe to upgrade.
    • MINOR (x.Y.z): Incremented when new features are added or small breaking changes (such as limited function signature changes) are introduced. Upgrading may require manual code adjustments.
    • MAJOR (X.y.z): Incremented for significant, substantial changes to public interfaces (classes, methods, types), behaviors, or semantics that require extensive code reworking.

  10. Switching between Service Account and User in CCG

    main

    Because com.box.sdkgen follows an immutable design, switching subjects (Service Account vs User) does not modify the existing auth object. Instead, use withUserSubject(String userId) or withEnterpriseSubject(String enterpriseId) to return a new BoxCCGAuth instance. The original instance remains unchanged.

    // Switch to user context
BoxCCGAuth userAuth = auth.withUserSubject("USER_ID");
BoxClient userClient = new BoxClient(userAuth);

// Switch to enterprise context
BoxCCGAuth entAuth = auth.withEnterpriseSubject("ENTERPRISE_ID");
BoxClient entClient = new BoxClient(entAuth);

  11. How event deduplication works in EventStream

    main
    The EventStream class provides automatic deduplication. It tracks events based on their eventId; if the same event is received multiple times from the Box API, the SDK ensures it is only emitted once to your listeners/iterator.

  12. Understand the differences between v4 and v10 SDKs

    main

    The v10 release of box-java-sdk is auto-generated from the OpenAPI Specification, whereas v4 and earlier were manually maintained. This change introduces a new package structure:

    • com.box.sdk: The legacy, manually maintained package used in v4.
    • com.box.sdkgen: The new, auto-generated package introduced in v10.

    Migration Strategy: If you are upgrading, you can use version 5 as an intermediate step to consolidate both packages. This allows you to use new features from com.box.sdkgen while keeping existing code in com.box.sdk unchanged. However, full migration to the v10 generated SDK is recommended.