Introduction

1. Basic Description

  Polyv Video on Demand is built on the company's years of video technology expertise. Based on professional video encryption technology, cross-platform video codec technology, and large-scale video content delivery networks, it provides stable, smooth, secure, and high-concurrency audio and video services.

  Polyv VOD Java SDK allows you to easily access Polyv VOD video cloud services without complex programming, enabling cloud-based video-on-demand related services.

  Polyv VOD Java SDK is implemented based on the Polyv VOD API, wrapping and optimizing it to free B-end users from common tasks. It encapsulates and optimizes API call logic and exception handling. B-end users only need to encapsulate request parameters and hand them over to the Polyv VOD Java SDK for processing. After processing, the SDK returns results, and the B-end continues its business logic based on the returned data. Currently, the Polyv VOD Java SDK covers most commonly used API operations, including video upload, video editing, video markers, subtitle management, danmaku management, and courseware management.

  If you encounter any issues while using the Polyv VOD Java SDK, please contact Online Customer Service to ask after-sales technical support. Please submit the runtime environment, operation steps, error feedback information, and contact details together to facilitate quick problem identification and resolution.

2. Overall SDK Design

1. B-end administrators upload video information via the SDK, such as videos, video watermarks, video preview images, video subtitles, and other basic information.

2. B-end administrators edit and manage videos via the SDK, such as basic video information, video categories, encryption settings, video progress bar markers, etc.

3. B-end administrators distribute video addresses to C-end viewers, or distribute viewing page addresses embedded with a player to viewers.

4. C-end viewers watch the videos uploaded by B-end administrators by opening the viewing address link or scanning a QR code.

5. B-end administrators can view C-end viewers' viewing status and statistical analysis data, completing the VOD business loop.

3. Detailed SDK Design

4. SDK Business Logic Analysis

• Prerequisite: SDK Global Initialization. Global parameters must be configured before calling the SDK. Configurable parameters include account information (userId, secretKey) and HTTP connection pool parameters (timeout, maxClientNum). See Initialization for details.
• SDK Global Parameter Injection: The SDK injects globally configured parameters into the request object.
• Signature Generation: The SDK uses the VOD signature rules to generate a signature.
• Parameter Validity Check: The SDK uses a custom parameter validation tool to check input parameters. If any parameter is invalid, a PloyvSdkException will be thrown. The exception's message includes the specific field that failed validation. This is a runtime exception and must be caught to handle related business logic.
• Send HTTP Request, Get Return Data: The SDK initializes an HTTP connection pool during initialization. All SDK requests are sent through this connection pool.
• Parse Return Data: Parse the returned data. If the SDK call is successful, the response object is encapsulated and returned normally. If the server returns an error message, the SDK will throw a PloyvSdkException. The exception's message includes the specific server execution error information. This is a runtime exception and must be caught to handle related business logic.

5. Call Flow Template

  The above business flow diagram is parsed into code as follows. All calls to the Polyv VOD Java SDK can refer to the following call template (Global initialization only needs to be called once globally).

6. Dependency Component Version Description

The latest version of the Polyv Java SDK uses the following common components.

Recommendations for Jackson Component

If your project also uses the Jackson component, there is a potential risk: when a Jackson minor version mismatch occurs at runtime (e.g., jackson-databind vs. jackson-core/jackson-annotations different minor versions, or inconsistency with other dependencies in your business), it may trigger:

• NoSuchMethodError
• NoClassDefFoundError
• ClassCastException

Recommendations:

1. Unify the Jackson three-piece version in your project (jackson-bom or Spring Boot BOM). Ensure jackson-core / jackson-databind / jackson-annotations maintain the same minor version.
2. If your project must use a specific Jackson version (e.g., due to Spring Boot management), you can exclude Jackson when importing the Polyv SDK, and let your project provide the Jackson version uniformly.

Example: Exclude Jackson transitively from Polyv SDK

<dependency>
  <groupId>net.polyv</groupId>
  <artifactId>polyv-java-live-sdk</artifactId>
  <version>xxx</version>
  <exclusions>
    <exclusion>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-core</artifactId>
    </exclusion>
    <exclusion>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
    </exclusion>
    <exclusion>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-annotations</artifactId>
    </exclusion>
  </exclusions>
</dependency>

<!-- 再由你的项目统一指定 Jackson 版本（示意） -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.fasterxml.jackson</groupId>
      <artifactId>jackson-bom</artifactId>
      <version>${jackson.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Recommendations for Other Common Components

slf4j-api

• Spring Boot 2.x ecosystem typically remains on SLF4J 1.7.x
• Spring Boot 3.x ecosystem upgrades to SLF4J 2.0.x
• Recommendations:
  • When using Spring Boot, prioritize letting the Spring Boot BOM manage logging-related dependency versions; avoid explicitly fixing a version inconsistent with the BOM in your business project.
  • If your project explicitly introduces implementations like slf4j-simple, log4j-slf4j-impl, ensure only one implementation is retained (otherwise, "multiple bindings/providers" type issues may occur).

httpclient

• HttpClient 4.x (org.apache.http.*) and HttpClient 5.x (org.apache.hc.*) can coexist, generally without issues, but it is recommended to avoid mixing two sets of versions in the same project.

Recommended Method for Resolving Dependency Conflicts

Execute in your project root directory (Maven):

1. View the final effective version (recommend adding -Dverbose):

mvn dependency:tree -Dverbose

2. Locate a specific component (example: Jackson / HttpClient):

mvn dependency:tree -Dverbose -Dincludes=com.fasterxml.jackson.core:jackson-databind
mvn dependency:tree -Dverbose -Dincludes=org.apache.httpcomponents:httpclient

3. Determine who introduced a specific version (observe the "nearest-wins" path in the tree), then decide:

• Use dependencyManagement to unify the version
• Or use exclusions at the import point