JRXML Local Verification

Halaman ini menjelaskan cara menguji file JRXML di laptop — compile dan render PDF tanpa men-deploy ke server InfiniteERP. Wajib dilakukan sebelum JRXML baru/diubah dipasang di server.

Kenapa Verifikasi Lokal

• Kesalahan JRXML (ekspresi tidak valid, field tidak dideklarasikan, class salah) baru ketahuan saat compile — bukan dari membaca XML.
• Menguji di server berarti menyentuh sistem produksi; di laptop cukup 1 perintah Java.
• Klaim "compatible" harus dibuktikan dengan hasil compile terhadap versi library yang sama dengan server (6.0.0), bukan versi lain.

Classpath (Terbukti Jalan)

Unduh dari Maven Central, taruh dalam satu folder (misal lib6/):

Jar	Fungsi
jasperreports-6.0.0.jar	Engine report — versi sama dengan server
jasperreports-fonts-6.0.0.jar	Font extension — sama dengan server
commons-digester-2.1.jar, commons-collections-3.2.2.jar, commons-beanutils-1.9.4.jar, commons-logging-1.2.jar	Dependensi parsing
ecj-4.4.2.jar	Compiler ekspresi (JDT)
itextpdf-5.5.13.3.jar	Export PDF (JR 6.x memakai package com.itextpdf)
itext-pdfa-5.5.13.3.jar	Wajib — PdfAWriter dipisah ke jar ini

Jebakan versi yang sudah ditemukan:

• JR 6.x tidak memakai iText lawas com.lowagie (itu milik JR 5.x). Tanpa itextpdf, export gagal: NoClassDefFoundError: com/itextpdf/text/DocumentException.
• Tanpa itext-pdfa, export gagal: NoClassDefFoundError: com/itextpdf/text/pdf/PdfAWriter.
• Teruji jalan di Java 17.

Langkah

1. Compile

<syntaxhighlight lang="java"> JasperReport rep = JasperCompileManager.compileReport("report.jrxml"); </syntaxhighlight>

Compile sukses = JRXML valid dan kompatibel dengan JR 6.0.0.

2. Fill dengan data dummy

Report ber-query SQL tidak butuh database untuk diuji — lewatkan datasource map:

<syntaxhighlight lang="java"> Map<String,Object> row = new HashMap<>(); row.put("bpnmae", "PT CONTOH PELANGGAN"); row.put("pricestd", new BigDecimal("5000000")); // ... isi semua field sesuai deklarasi <field> di JRXML

Map<String,Object> params = new HashMap<>(); params.put("IMAGE_DIR", "/path/ke/folder/gambar");

JasperPrint print = JasperFillManager.fillReport(rep, params,

   new JRMapCollectionDataSource(java.util.Collections.singletonList(row)));

</syntaxhighlight>

Catatan: ImageIO membaca gambar berdasarkan konten, bukan ekstensi — file PNG bernama .jpg tetap ter-render (berguna untuk placeholder).

3. Export PDF

<syntaxhighlight lang="java"> JRPdfExporter exporter = new JRPdfExporter(); exporter.setParameter(JRExporterParameter.JASPER_PRINT, print); exporter.setParameter(JRExporterParameter.OUTPUT_FILE_NAME, "sample.pdf"); exporter.exportReport(); </syntaxhighlight>

Jalankan: java -cp ".:lib6/*" NamaVerifier

4. Cek hasil

• Buka PDF dan periksa visual: overlap, teks terpotong, alignment angka.
• Untuk elemen grafis kritis (accent bar, latar blok), bisa dicek deterministik: konversi PDF ke PNG lalu baca warna piksel pada koordinat yang diharapkan. Cara ini terbukti menangkap bug outline hitam pada <rectangle> (lihat JRXML Best Practices).

Tool CLI: jrxmlcheck

Untuk pengguna non-programmer tersedia tool CLI jrxmlcheck — satu perintah, tanpa menulis Java.

Unduh & Pasang

1. Unduh Jrxmlcheck.zip (5 KB; halaman berkas: File:Jrxmlcheck.zip).
2. Ekstrak: unzip Jrxmlcheck.zip — terbentuk folder cli/.
3. Beri izin eksekusi (sekali saja): chmod +x cli/jrxmlcheck
4. Prasyarat: Java/JDK terpasang (teruji di Java 17), dan internet saat pertama dijalankan karena library JasperReports 6.0.0 diunduh otomatis dari Maven Central.

Cara Pakai

./cli/jrxmlcheck compile laporan.jrxml                     # cek valid & kompatibel JR 6.0.0
./cli/jrxmlcheck preview laporan.jrxml                     # buat PDF contoh, data otomatis
./cli/jrxmlcheck preview laporan.jrxml --images ./images   # pakai folder gambar (logo/stempel/ttd)
./cli/jrxmlcheck preview laporan.jrxml --data data.txt     # data sendiri, format: namafield=nilai

• Mode preview membaca deklarasi <field> di JRXML lalu membuat data contoh otomatis — langsung jalan tanpa menyiapkan apa pun. Jumlah baris contoh diatur dengan --rows N.
• Mode audit — pemeriksaan menyeluruh sebelum deploy:
  • Font — setiap fontName dicek terhadap isi jasperreports-fonts-6.0.0.jar (DejaVu Sans/Serif/Sans Mono + SansSerif/Serif/Monospaced). Font lain akan disubstitusi diam-diam di server → layout bergeser.
  • Path absolut pada imageExpression (mis. /home/zaien_aji/...) — harus diganti parameter seperti $P{IMAGE_DIR}.
  • Geometri — elemen yang keluar batas band atau lebar kolom (tidak akan tercetak utuh).
  • Variabel mati (variableExpression kosong) dan field/parameter tidak terpakai.
  • Jejak Jaspersoft Studio (splitType, property com.jaspersoft.studio.*) — jadi peringatan bila diaudit dengan --target ireport.
  • Elemen teks bertumpuk — dua elemen teks yang kotaknya beririsan >50% dari kotak terkecil (irisan tipis antar kolom kiri/kanan diabaikan karena umum & aman; teks di dalam kotak latar dan stempel-di-atas-tanda-tangan juga diabaikan — gambar bertumpuk hanya dicatat sebagai info).
  • Atribut PDF lawas (pdfFontName, pdfEncoding, isPdfEmbedded) — deprecated, migrasikan ke font extension.
  • Encoding file — JRXML wajib UTF-8 valid; file Latin-1/Windows-1252 ditolak sebelum compile dengan pesan yang menunjuk cara memperbaikinya (karakter •, · rawan rusak).
  • --strict: exit code 1 bila ada peringatan — cocok untuk gerbang CI sebelum deploy.

• File data sendiri: teks biasa, satu namafield=nilai per baris, baris # untuk komentar.
• Pesan error diringkas ke penyebab utama beserta daftar penyebab umum (field tidak dideklarasikan, salah ketik nama field, class field salah, ekspresi bukan Java valid).
• PDF hasil terbuka otomatis di macOS (nonaktifkan dengan --no-open); nama file diatur dengan --out.
• Petunjuk lengkap juga tersedia di README.txt dalam paket.

Validasi query ke database (--jdbc)

Menjalankan query JRXML ke PostgreSQL sungguhan — persis alur produksi:

./cli/jrxmlcheck audit laporan.jrxml \
    --jdbc jdbc:postgresql://HOST:5432/NAMA_DB --dbuser USER
# password: --dbpass PASS atau lebih aman env JRXMLCHECK_DBPASS
# override parameter: --param DOCUMENT_ID=XXX (boleh berulang)

Yang diverifikasi:

1. Query dieksekusi lewat fillReport(connection) — parameter default ikut dievaluasi JasperReports, jadi kesalahan nama tabel/kolom langsung ketahuan dengan pesan asli PostgreSQL.
2. Probe kolom: ResultSetMetaData hasil query dicocokkan dengan deklarasi <field> — tetap bekerja walau hasil query 0 baris (kasus alias salah yang tidak ketahuan saat fill biasa).
3. Gambar tidak perlu disiapkan: placeholder otomatis dibuat untuk nama file yang dirujuk imageExpression (bisa dioverride dengan --images).
4. Kolom query yang tidak dideklarasikan hanya dicatat sebagai INFO.

Driver PostgreSQL (42.7.3) ikut terunduh otomatis oleh wrapper. Teruji end-to-end memakai PostgreSQL 16 dengan skema mini ala Openbravo (c_invoice dkk).

Hasil yang Pernah Diverifikasi

• sales_invoice_SSD.jrxml (asli, iReport 5.6): compile OK di JR 5.6.0 dan 6.0.0
• Versi perbaikan (parameter IMAGE_DIR, variable mati dihapus): compile + render OK
• Layout modern tanpa border penuh: compile + render OK, cek piksel lolos