如何用Java通过JasperReports Server REST API部署输入控件？

阿华AIGC实验室

2026-5-9

我完全懂你这种联系Tibco支持无果、甚至怀疑官方文档可行性的挫败感——JasperReports的REST API确实经常让人摸不着头脑，尤其是输入控件部署这块的细节，官方文档要么语焉不详要么版本不对。

下面给你一个完全基于Java 11+内置HttpClient的极简实现，没有任何第三方HTTP框架，只依赖必要的Jasper模型类来处理JSON序列化，完美覆盖你需要的所有需求：

极简实现方案

1. 项目依赖（pom.xml）

只需要两个核心依赖：Jasper官方的REST模型类（用来规范输入控件的JSON结构，避免手动拼字符串出错），以及Jackson用来序列化/反序列化JSON：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.yourcompany</groupId>
    <artifactId>jasper-input-control-tool</artifactId>
    <version>1.0-SNAPSHOT</version>

    <dependencies>
        <!-- 必须和你的JasperServer版本完全匹配！比如你用7.2.0就用这个版本 -->
        <dependency>
            <groupId>com.jaspersoft.jasperserver</groupId>
            <artifactId>jrs-rest-client-model</artifactId>
            <version>7.2.0</version>
        </dependency>
        <!-- Jackson JSON处理，Jasper模型依赖这个 -->
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.13.4</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>11</source>
                    <target>11</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

2. 完整Java实现（单个文件）

这个文件包含认证、部署输入控件、查询所有输入控件三个核心功能，所有HTTP调用都用Java自带的HttpClient实现：

import com.fasterxml.jackson.databind.ObjectMapper;
import com.jaspersoft.jasperserver.dto.resources.ClientInputControl;
import com.jaspersoft.jasperserver.dto.resources.ClientListOfValues;
import com.jaspersoft.jasperserver.dto.resources.ClientResourceLookup;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class JasperInputControlManager {

    // -------------------------- 配置参数 --------------------------
    private static final String JASPER_SERVER_BASE = "http://your-jasper-server:8080/jasperserver";
    private static final String USERNAME = "admin"; // 替换为你的账号
    private static final String PASSWORD = "password"; // 替换为你的密码
    // 目标文件夹的完整URI，可从JasperWeb界面的文件夹属性中查看
    private static final String TARGET_FOLDER_URI = "/organizations/organization_1/my-folder";
    // -------------------------------------------------------------

    private final HttpClient httpClient;
    private final ObjectMapper objectMapper;
    private String authCookie; // 存储JSESSIONID用于后续请求

    public JasperInputControlManager() {
        this.httpClient = HttpClient.newHttpClient();
        this.objectMapper = new ObjectMapper();
    }

    /**
     * 步骤1：通过POST请求完成表单认证，获取JSESSIONID
     */
    public void login() throws Exception {
        Map<String, String> loginForm = new HashMap<>();
        loginForm.put("j_username", USERNAME);
        loginForm.put("j_password", PASSWORD);

        HttpRequest loginRequest = HttpRequest.newBuilder()
                .uri(URI.create(JASPER_SERVER_BASE + "/j_spring_security_check"))
                .header("Content-Type", "application/x-www-form-urlencoded")
                .POST(HttpRequest.BodyPublishers.ofString(mapToFormData(loginForm)))
                .build();

        HttpResponse<Void> response = httpClient.send(loginRequest, HttpResponse.BodyHandlers.discarding());

        // 从响应Cookie中提取JSESSIONID
        for (String cookie : response.headers().allValues("Set-Cookie")) {
            if (cookie.startsWith("JSESSIONID")) {
                authCookie = cookie.split(";")[0]; // 只取JSESSIONID部分，忽略其他属性
                break;
            }
        }

        if (authCookie == null) {
            throw new RuntimeException("登录失败：未获取到JSESSIONID");
        }
    }

    /**
     * 步骤2：POST部署输入控件到指定文件夹
     */
    public void deployInputControl(ClientInputControl inputControl) throws Exception {
        String icJson = objectMapper.writeValueAsString(inputControl);

        HttpRequest deployRequest = HttpRequest.newBuilder()
                .uri(URI.create(JASPER_SERVER_BASE + "/rest_v2/resources" + TARGET_FOLDER_URI))
                .header("Content-Type", "application/json")
                .header("Cookie", authCookie)
                .POST(HttpRequest.BodyPublishers.ofString(icJson))
                .build();

        HttpResponse<String> response = httpClient.send(deployRequest, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 201) { // 201表示创建成功
            throw new RuntimeException("部署失败：" + response.body());
        }
        System.out.println("输入控件部署成功！");
    }

    /**
     * 步骤3：GET请求获取所有输入控件列表（返回JSON，自动反序列化为对象列表）
     */
    public List<ClientResourceLookup> getAllInputControls() throws Exception {
        HttpRequest listRequest = HttpRequest.newBuilder()
                .uri(URI.create(JASPER_SERVER_BASE + "/rest_v2/resources?type=inputControl&recursive=true"))
                .header("Cookie", authCookie)
                .GET()
                .build();

        HttpResponse<String> response = httpClient.send(listRequest, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new RuntimeException("获取输入控件列表失败：" + response.body());
        }

        // 把JSON响应转为Java对象列表
        return objectMapper.readValue(
                response.body(),
                objectMapper.getTypeFactory().constructCollectionType(List.class, ClientResourceLookup.class)
        );
    }

    // 辅助方法：把Map转为表单提交的字符串格式
    private String mapToFormData(Map<String, String> data) {
        StringBuilder sb = new StringBuilder();
        for (Map.Entry<String, String> entry : data.entrySet()) {
            if (sb.length() > 0) sb.append("&");
            sb.append(entry.getKey()).append("=").append(entry.getValue());
        }
        return sb.toString();
    }

    // 测试主方法
    public static void main(String[] args) {
        try {
            JasperInputControlManager manager = new JasperInputControlManager();

            // 1. 登录认证
            manager.login();

            // 2. 创建一个示例输入控件（单选下拉列表）
            ClientInputControl sampleIC = new ClientInputControl()
                    .setName("department_selector")
                    .setLabel("部门选择器")
                    .setType("singleSelect")
                    .setVisible(true)
                    .setMandatory(true)
                    .setListOfValues(new ClientListOfValues()
                            .addValue("技术部", "tech")
                            .addValue("市场部", "marketing")
                            .addValue("财务部", "finance"));

            // 3. 部署到目标文件夹
            manager.deployInputControl(sampleIC);

            // 4. 查询所有输入控件并打印
            List<ClientResourceLookup> allICs = manager.getAllInputControls();
            System.out.println("\n所有输入控件：");
            allICs.forEach(ic -> System.out.println("- " + ic.getLabel() + " (URI: " + ic.getUri() + ")"));

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

关键注意事项（踩过的坑）

版本必须完全匹配：jrs-rest-client-model的版本必须和你的JasperReports Server版本一模一样，否则会出现JSON序列化/反序列化错误——这是官方文档最容易忽略的点，也是很多人部署失败的原因。
文件夹URI要正确：TARGET_FOLDER_URI必须是JasperServer中已存在的文件夹的完整URI，你可以在Web界面中打开文件夹的“属性”查看这个值（比如/organizations/organization_1/reports）。
XSRF保护处理：如果你的JasperServer启用了XSRF保护，需要在登录后额外提取XSRF-TOKEN，并在后续请求中添加X-XSRF-TOKEN请求头。代码中预留了扩展空间，你可以在login()方法中添加提取逻辑。
输入控件类型：示例中是单选下拉列表，你可以根据需求修改ClientInputControl的属性，比如改为文本输入、多选列表等，参考JasperServer的输入控件JSON结构（虽然官方文档烂，但你可以通过Web界面创建一个控件后，用GET请求查看它的JSON来参考）。