{"record":{"id":"4ddc1474fa49dd19","repo":"spring-projects/spring-ai","slug":"this-is-a-utility-class-and-cannot-be-instantiated-4ddc14","errorCode":null,"errorMessage":"This is a utility class and cannot be instantiated","messagePattern":"This is a utility class and cannot be instantiated","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"spring-ai-test/src/main/java/org/springframework/ai/utils/AudioPlayer.java","lineNumber":35,"sourceCode":"package org.springframework.ai.utils;\n\nimport java.io.BufferedInputStream;\nimport java.io.ByteArrayInputStream;\nimport java.io.FileInputStream;\nimport java.io.InputStream;\n\nimport javax.sound.sampled.AudioInputStream;\nimport javax.sound.sampled.AudioSystem;\nimport javax.sound.sampled.Clip;\n\n/**\n * @author Christian Tzolov\n * @since 1.0.0\n */\npublic final class AudioPlayer {\n\n\tprivate AudioPlayer() {\n\t\tthrow new UnsupportedOperationException(\"This is a utility class and cannot be instantiated\");\n\t}\n\n\tpublic static void main(String[] args) throws Exception {\n\t\tplay(new BufferedInputStream(new FileInputStream(args[0])));\n\t}\n\n\tpublic static void play(byte[] data) {\n\t\tplay(new BufferedInputStream(new ByteArrayInputStream(data)));\n\t}\n\n\tpublic static void play(InputStream data) {\n\n\t\ttry {\n\t\t\ttry (AudioInputStream audio = AudioSystem.getAudioInputStream(data); Clip clip = AudioSystem.getClip()) {\n\t\t\t\tclip.open(audio);\n\t\t\t\tclip.start();\n\t\t\t\t// wait to start\n\t\t\t\twhile (!clip.isRunning()) {","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/spring-ai-test/src/main/java/org/springframework/ai/utils/AudioPlayer.java#L17-L53","documentation":"AudioPlayer is a final utility class whose private constructor deliberately throws UnsupportedOperationException to prevent instantiation. The library throws this if any code attempts to construct an AudioPlayer instance; the class is meant to be used only via its static methods (e.g. play(...)).","triggerScenarios":"Calling new AudioPlayer() anywhere in user code, or via reflection/deserialization; also hit by tools (e.g. code coverage, Jacoco) that generate synthetic constructors invoking the private constructor.","commonSituations":"Copy-pasted code instantiating a utility class instead of calling the static play method; test coverage tooling triggering the private constructor in instrumented builds.","solutions":["Do not instantiate: call static methods directly, e.g. AudioPlayer.play(new BufferedInputStream(new FileInputStream(file))).","If coverage tools cause the error, exclude the class from instrumentation or add an inline filter for the private constructor.","Use reflection with setAccessible only if absolutely required, knowing UnsupportedOperationException will still be thrown by design."],"exampleFix":"// before\nAudioPlayer player = new AudioPlayer();\n// after\nAudioPlayer.play(new BufferedInputStream(new FileInputStream(\"audio.wav\")));","handlingStrategy":"type-guard","validationCode":"// Java: never instantiate utility classes; check modifier before reflective use\nif (!Modifier.isStatic(0) && !AudioPlayer.class.getSimpleName().isEmpty()) {\n    Constructor<AudioPlayer> c = AudioPlayer.class.getDeclaredConstructor();\n    if (c != null) throw new IllegalStateException(\"Do not instantiate AudioPlayer; use static play()\");\n}","typeGuard":"// Use the class only through static dispatch\nstatic void safePlay(InputStream in) throws Exception {\n    java.util.Objects.requireNonNull(in, \"input stream required\");\n    AudioPlayer.play(in);\n}","tryCatchPattern":"// Usually not caught; only needed for coverage-tool induced synthetic calls\ntry {\n    new AudioPlayer();\n} catch (UnsupportedOperationException expected) {\n    // by design; switch to static usage\n}","preventionTips":["Call AudioPlayer.play(InputStream) statically; never store instances.","Exclude utility classes with private constructors from JaCoCo coverage requirements.","Look for 'utility class' in javadoc before instantiating framework helper types."],"tags":["utility-class","instantiation","unsupported-operation"],"backgroundTag":"unsupported-operation","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}