refactor: polish dcm4che5 backend after pre-PR audit

Followups from a pre-PR audit of the dcm4che5 backend:

- Add Object-VR overloads on OieDicomObject for putString / putInt /
  putBytes / putFragments, delegating via toString(). Preserves backward
  compatibility for transformer scripts passing a library-specific VR
  constant (e.g., dcm4che2's VR.PN) when the method surface is the
  version-neutral wrapper.

- Simplify OieDicomObject.getInt(int, int) default from a two-step
  get(tag) + getInt(tag) lookup to a single contains(tag) + getInt(tag).

- Upgrade trace->warn for Dcm5 no-op setters (setFileBufferSize,
  setTranscoderBufferSize, setDestination). These paths are only reached
  when the user explicitly set a non-default value, so the warn has zero
  noise on default configs and surfaces an otherwise-silent ignored
  setting. Also documents the long-standing upstream behavior of
  DICOMReceiver 'dest' being ignored on both backends (MirthDcmRcv's
  onCStoreRQ override streams directly to the channel and never consults
  DcmRcv.setDestination).

- Document no-op settings and DICOMUtil API migration in
  docs/dcm4che5-migration-guide.md.

Signed-off-by: Jesse Dowell <jesse.dowell@gmail.com>

Author: jcdlbs

docs/dcm4che5-migration-guide.md

@@ -34,7 +34,7 @@ To revert, change the value back to `dcm4che2` (or remove the line) and restart.
 
 | Area | Behavior |
 |------|----------|
-| Channel properties | All DICOM Listener and Sender properties work identically |
+| Channel properties | Listener and Sender UI properties work identically (see [Settings with no effect on dcm4che5](#settings-with-no-effect-on-dcm4che5) for two pure-tuning flags that are ignored) |
 | Source map keys | Same keys populated: `localApplicationEntityTitle`, `remoteApplicationEntityTitle`, `localAddress`, `localPort`, `remoteAddress`, `remotePort` |
 | DICOM object serialization | Byte-level output differs (different FMI implementation version UIDs), but all tag values are semantically equivalent |
 | C-STORE, C-ECHO | Both work through the standard channel lifecycle |
@@ -63,6 +63,46 @@ If your channel logic inspects DICOM element names (not tag numbers), be aware t
 dicomObject.getString(Tag.PatientName)  // works on both
 ```
 
+### Settings with no effect
+
+A few Listener and Sender UI fields have no corresponding implementation on the dcm4che5 backend. The dcm4che2 backend behavior is preserved unchanged. A `WARN`-level log is emitted on channel start when any of these are set to a non-default value on dcm4che5:
+
+| UI setting | Connector | Note |
+|---|---|---|
+| `bufSize` | Listener | File buffer size. dcm4che3 manages buffers internally; no equivalent API |
+| `bufSize` | Sender | Transcoder buffer size. dcm4che3 manages buffers internally via `DataWriterAdapter` |
+| `dest` (Store Received Objects in Directory) | Listener | Silently ignored on **both backends** — a long-standing upstream behavior. `MirthDcmRcv` streams DIMSE data directly to the channel and never consults this setting on either backend |
+
+None of these affect data integrity. Messages still arrive and dispatch through the channel correctly. The `bufSize` flags are pure performance tuning; revert `dicom.library` to `dcm4che2` if the throughput difference matters for your deployment.
+
+All other UI settings — TLS options, AE titles, timeouts, PDU lengths, transfer syntax selection, storage commitment, user identity, and priority — work identically on both backends.
+
+### DICOMUtil API (user transformer scripts)
+
+`DICOMUtil.byteArrayToDicomObject()` and `dicomObjectToByteArray()` now return / accept the version-neutral `OieDicomObject` type. For the vast majority of transformer scripts this change is invisible — Rhino's duck typing plus Object-type overloads on `OieDicomObject` mean existing calls keep working unchanged:
+
+```javascript
+// Existing scripts continue to work on default (dcm4che2) without changes:
+var dcm = DICOMUtil.byteArrayToDicomObject(bytes, false);
+dcm.getString(Tag.PatientName);                    // same method exists on OieDicomObject
+dcm.putString(Tag.PatientName, VR.PN, "SMITH");    // Object-overload routes via VR.toString()
+```
+
+Only these specific patterns require a one-line change:
+
+| Pattern | Change |
+|---|---|
+| `(DicomObject) DICOMUtil.byteArrayToDicomObject(...)` explicit cast | `(DicomObject) DICOMUtil.byteArrayToDicomObject(...).unwrap()` |
+| `dcm instanceof DicomObject` | `dcm.unwrap() instanceof DicomObject` |
+| Passing the result to a Java API that expects `org.dcm4che2.data.DicomObject` | Pass `dcm.unwrap()` instead |
+
+The recommended version-neutral pattern for new scripts is to use string VR codes instead of library-specific constants:
+
+```javascript
+// Works identically on both backends — no dependency on VR class:
+dcm.putString(Tag.PatientName, "PN", "SMITH");
+```
+
 ## TLS Configuration
 
 ### Standard UI TLS Options

server/src/com/mirth/connect/connectors/dimse/dicom/OieDicomObject.java

@@ -36,8 +36,7 @@ default String getString(int tag, String defaultValue) {
      * if the tag is not present.
      */
     default int getInt(int tag, int defaultValue) {
-        OieDicomElement elem = get(tag);
-        return elem != null ? getInt(tag) : defaultValue;
+        return contains(tag) ? getInt(tag) : defaultValue;
     }
 
     OieDicomElement get(int tag);
@@ -79,14 +78,41 @@ default int getInt(int tag, int defaultValue) {
 
     void putString(int tag, String vr, String value);
 
+    /**
+     * Overload accepting any {@code Object} as the VR argument. Delegates to
+     * {@link #putString(int, String, String)} using {@code vr.toString()}.
+     *
+     * <p>Preserves backward compatibility for transformer scripts that pass a
+     * library-specific VR constant (e.g., dcm4che2's {@code VR.PN}), whose
+     * {@code toString()} returns the two-letter VR code.
+     */
+    default void putString(int tag, Object vr, String value) {
+        putString(tag, vr != null ? vr.toString() : null, value);
+    }
+
     void putInt(int tag, String vr, int value);
 
+    /** Object-VR overload of {@link #putInt(int, String, int)}; see {@link #putString(int, Object, String)}. */
+    default void putInt(int tag, Object vr, int value) {
+        putInt(tag, vr != null ? vr.toString() : null, value);
+    }
+
     void putBytes(int tag, String vr, byte[] value);
 
+    /** Object-VR overload of {@link #putBytes(int, String, byte[])}; see {@link #putString(int, Object, String)}. */
+    default void putBytes(int tag, Object vr, byte[] value) {
+        putBytes(tag, vr != null ? vr.toString() : null, value);
+    }
+
     OieDicomElement putSequence(int tag);
 
     OieDicomElement putFragments(int tag, String vr, boolean bigEndian, int capacity);
 
+    /** Object-VR overload of {@link #putFragments(int, String, boolean, int)}; see {@link #putString(int, Object, String)}. */
+    default OieDicomElement putFragments(int tag, Object vr, boolean bigEndian, int capacity) {
+        return putFragments(tag, vr != null ? vr.toString() : null, bigEndian, capacity);
+    }
+
     void add(OieDicomElement element);
 
     OieDicomElement remove(int tag);

server/src/com/mirth/connect/connectors/dimse/dicom/dcm5/Dcm5DicomReceiver.java

@@ -273,8 +273,13 @@ public void setHostname(String hostname) {
 
     @Override
     public void setDestination(String destination) {
-        // Not used — dcm5 receiver dispatches directly to the channel, not to filesystem
-        logger.trace("setDestination ignored in dcm5 receiver (no filesystem storage): " + destination);
+        // Matches dcm4che2's de facto behavior: MirthDcmRcv streams DIMSE data directly
+        // to the channel and never consults DcmRcv.setDestination, so the UI flag has
+        // been a no-op on both backends. Only reached when the user explicitly set a
+        // non-blank value in the Listener's "Store Received Objects in Directory" field.
+        logger.warn("destination={} has no effect on either DICOM backend (the flag has been "
+                + "silently ignored upstream for years). Remove this setting to clear the warning.",
+                destination);
     }
 
     @Override
@@ -345,9 +350,11 @@ public void setReceiveBufferSize(int size) {
 
     @Override
     public void setFileBufferSize(int size) {
-        // dcm5 receiver writes directly to ByteArrayOutputStream, not filesystem.
-        // No file buffer applicable.
-        logger.trace("setFileBufferSize ignored in dcm5 receiver: " + size);
+        // dcm5 receiver streams directly to memory, with no file buffer concept.
+        // Only reached when the user explicitly changed bufSize from default,
+        // so warn instead of trace to surface the ignored setting.
+        logger.warn("bufSize={} has no effect on dcm4che5 receiver (dcm4che3 manages buffers internally). "
+                + "Revert dicom.library=dcm4che2 if this tuning is load-bearing.", size);
     }
 
     @Override

server/src/com/mirth/connect/connectors/dimse/dicom/dcm5/Dcm5DicomSender.java

@@ -197,8 +197,11 @@ public void setMaxOpsInvoked(int maxOps) {
 
     @Override
     public void setTranscoderBufferSize(int size) {
-        // dcm4che5 does not have a transcoder buffer — transcoding is handled internally.
-        logger.trace("setTranscoderBufferSize ignored in dcm5 sender: " + size);
+        // dcm4che5 has no transcoder buffer — transcoding is handled internally via DataWriterAdapter.
+        // Only reached when the user explicitly changed bufSize from default, so warn instead of
+        // trace to surface the ignored setting.
+        logger.warn("bufSize={} has no effect on dcm4che5 sender (dcm4che3 manages transcoder buffers internally). "
+                + "Revert dicom.library=dcm4che2 if this tuning is load-bearing.", size);
     }
 
     @Override

server/test/com/mirth/connect/connectors/dimse/dicom/dcm5/Dcm5DicomObjectTest.java

@@ -57,6 +57,28 @@ public void testGetReturnsNullForMissingTag() {
         assertEquals(0, obj.getInt(Tag.Rows));
     }
 
+    @Test
+    public void testPutStringAcceptsObjectVrViaToString() {
+        // Simulates a user transformer script passing a library-specific VR constant
+        // (e.g., dcm4che2 VR.PN) — the Object overload delegates via toString().
+        Object libraryVr = new Object() {
+            @Override public String toString() { return "PN"; }
+        };
+        Dcm5DicomObject obj = new Dcm5DicomObject();
+        obj.putString(Tag.PatientName, libraryVr, "Doe^John");
+        assertEquals("Doe^John", obj.getString(Tag.PatientName));
+    }
+
+    @Test
+    public void testPutIntAcceptsObjectVrViaToString() {
+        Object libraryVr = new Object() {
+            @Override public String toString() { return "US"; }
+        };
+        Dcm5DicomObject obj = new Dcm5DicomObject();
+        obj.putInt(Tag.Rows, libraryVr, 512);
+        assertEquals(512, obj.getInt(Tag.Rows));
+    }
+
     @Test
     public void testPutSequence() {
         Dcm5DicomObject obj = new Dcm5DicomObject();