{"record":{"id":"6b51a6802e8bfca4","repo":"java-native-access/jna","slug":"immutable-reference","errorCode":null,"errorMessage":"immutable reference","messagePattern":"immutable reference","errorType":"validation","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"contrib/platform/src/com/sun/jna/platform/win32/WinNT.java","lineNumber":1393,"sourceCode":"        public HANDLE(Pointer p) {\n            setPointer(p);\n            immutable = true;\n        }\n\n        /** Override to the appropriate object for INVALID_HANDLE_VALUE. */\n        @Override\n        public Object fromNative(Object nativeValue, FromNativeContext context) {\n            Object o = super.fromNative(nativeValue, context);\n            if (WinBase.INVALID_HANDLE_VALUE.equals(o)) {\n                return WinBase.INVALID_HANDLE_VALUE;\n            }\n            return o;\n        }\n\n        @Override\n        public void setPointer(Pointer p) {\n            if (immutable) {\n                throw new UnsupportedOperationException(\"immutable reference\");\n            }\n\n            super.setPointer(p);\n        }\n\n        @Override\n        public String toString() {\n            return String.valueOf(getPointer());\n        }\n    }\n\n    /**\n     * LPHANDLE\n     */\n    public static class HANDLEByReference extends ByReference {\n        public HANDLEByReference() {\n            this(null);\n        }","sourceCodeStart":1375,"sourceCodeEnd":1411,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/contrib/platform/src/com/sun/jna/platform/win32/WinNT.java#L1375-L1411","documentation":"Some WinNT structure classes offer an immutable mode in which the pointer is fixed at construction; calling setPointer on such an instance throws this UnsupportedOperationException. The design prevents callers from retargeting a reference that must stay bound to its original native memory (typically a const/out-style reference).","triggerScenarios":"Calling setPointer (directly, or via structure read/write that assigns pointers) on an immutable instance — e.g. reusing a constant/immutable reference object across multiple native calls or trying to rebind it to a new buffer.","commonSituations":"Reusing a shared immutable reference as an output parameter across calls; copying field values from one structure into an immutable-typed field; accidentally treating a by-reference constant as a mutable buffer.","solutions":["Create a new mutable instance for each call instead of reusing the immutable one.","If mutability is required, construct the object in non-immutable mode (use the appropriate constructor, not the immutable/constant factory).","Use a plain Pointer/Memory buffer that you own and pass that instead.","Check for accidental writes: guard re-binding behind a copy of the structure."],"exampleFix":"// before\nref.setPointer(newBuffer); // UnsupportedOperationException if immutable\n// after\nPointerType mutable = new PointerType();\nmutable.setPointer(newBuffer);","handlingStrategy":"type-guard","validationCode":"// ensure the reference is not immutable before rebinding\n// (immutable instances are created via the immutable/constant constructors)","typeGuard":"static boolean isMutableRef(PointerType p) {\n    try {\n        p.setPointer(p.getPointer());\n        return true;\n    } catch (UnsupportedOperationException e) {\n        return false;\n    }\n}","tryCatchPattern":"try {\n    ref.setPointer(newBuffer);\n} catch (UnsupportedOperationException e) {\n    ref = new PointerType(); // fresh mutable instance\n    ref.setPointer(newBuffer);\n}","preventionTips":["Never reuse immutable reference objects as out-parameters.","Create a new instance per native call when rebinding is needed.","Check the constructor used — constant/immutable factories yield read-only references."],"tags":["windows","jna","immutability"],"backgroundTag":"unsupported-operation","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}