Merge pull request #214 from javaevolved/copilot/explicit-charset-file-io

Add pattern: default-charset file I/O to explicit StandardCharsets

Author: brunoborges

content/io/explicit-charset-file-io.yaml

@@ -0,0 +1,48 @@
+---
+id: 100472fa-74b1-442f-b89d-3e6e8adcc1b1
+slug: "explicit-charset-file-io"
+title: "Default-charset file I/O to explicit StandardCharsets"
+category: "io"
+difficulty: "beginner"
+jdkVersion: "7"
+oldLabel: "Platform-default charset"
+modernLabel: "Explicit standard charset"
+oldApproach: "Platform-default charset"
+modernApproach: "Explicit standard charset"
+oldCode: |-
+  try (Reader reader = new FileReader(path.toFile())) {
+      return readAll(reader);
+  }
+modernCode: |-
+  try (BufferedReader reader = Files.newBufferedReader(
+          path, StandardCharsets.UTF_8)) {
+      return readAll(reader);
+  }
+summary: "Use Files readers and writers with StandardCharsets constants instead of platform-default charset behavior and charset-name lookup."
+explanation: "Reader and writer constructors that rely on the default charset make file behavior depend on the runtime environment. Files.newBufferedReader() and newBufferedWriter() accept an explicit Charset, while StandardCharsets provides guaranteed constants such as UTF_8 without string lookup or UnsupportedCharsetException. This combines the explicit-file-encoding and Charset.forName(\"UTF-8\") migrations into one coherent pattern."
+whyModernWins:
+- icon: "🌍"
+  title: "Portable results"
+  desc: "The same bytes decode identically on every machine."
+- icon: "🔒"
+  title: "Predefined constant"
+  desc: "StandardCharsets.UTF_8 cannot contain a misspelled charset name."
+- icon: "🧩"
+  title: "Modern file API"
+  desc: "Path, buffering, and encoding are expressed in one operation."
+support:
+  state: "available"
+  description: "Widely available since JDK 7 (July 2011)"
+prev: "io/writing-files"
+next: "io/inputstream-transferto"
+related:
+- "io/reading-files"
+- "io/writing-files"
+- "io/path-of"
+tags:
+- io
+docs:
+- title: "Files.newBufferedReader(Path, Charset)"
+  href: "https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/nio/file/Files.html#newBufferedReader(java.nio.file.Path,java.nio.charset.Charset)"
+- title: "StandardCharsets"
+  href: "https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/nio/charset/StandardCharsets.html"

content/io/inputstream-transferto.yaml

@@ -33,7 +33,7 @@ whyModernWins:
 support:
   state: "available"
   description: "Widely available since JDK 9 (Sept 2017)"
-prev: "io/writing-files"
+prev: "io/explicit-charset-file-io"
 next: "io/path-of"
 related:
 - "io/writing-files"

content/io/writing-files.yaml

@@ -38,7 +38,7 @@ support:
   state: "available"
   description: "Widely available since JDK 11 (Sept 2018)"
 prev: "io/reading-files"
-next: "io/inputstream-transferto"
+next: "io/explicit-charset-file-io"
 related:
 - "io/reading-files"
 - "io/http-client"

proof/io/ExplicitCharsetFileIo.java

@@ -0,0 +1,27 @@
+///usr/bin/env jbang "$0" "$@" ; exit $?
+//JAVA 25+
+import java.io.BufferedReader;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+/// Proof: explicit-charset-file-io
+/// Source: content/io/explicit-charset-file-io.yaml
+void main() throws Exception {
+    var path = Path.of(System.getProperty("java.io.tmpdir"), "proof-charset.txt");
+    Files.writeString(path, "content", StandardCharsets.UTF_8);
+
+    try (BufferedReader reader = Files.newBufferedReader(
+            path, StandardCharsets.UTF_8)) {
+        readAll(reader);
+    }
+}
+
+String readAll(BufferedReader reader) throws Exception {
+    var sb = new StringBuilder();
+    String line;
+    while ((line = reader.readLine()) != null) {
+        sb.append(line);
+    }
+    return sb.toString();
+}

social/queue.txt

@@ -129,3 +129,4 @@ security/security-manager-migration
 tooling/runtime-exec-to-process-builder
 language/raw-collections-to-generics
 concurrency/thread-stop-to-cooperative-cancellation
+io/explicit-charset-file-io

social/tweets.yaml

@@ -1307,4 +1307,14 @@ concurrency/thread-stop-to-cooperative-cancellation: |-
 
   🔗 https://javaevolved.github.io/concurrency/thread-stop-to-cooperative-cancellation.html
 
+  #Java #JavaEvolved
+io/explicit-charset-file-io: |-
+  ☕ Default-charset file I/O to explicit StandardCharsets
+
+  Use Files readers and writers with StandardCharsets constants instead of…
+
+  Platform-default charset → Explicit standard charset (JDK 7+)
+
+  🔗 https://javaevolved.github.io/io/explicit-charset-file-io.html
+
   #Java #JavaEvolved

translations/content/ar/io/explicit-charset-file-io.yaml

@@ -0,0 +1,17 @@
+title: "تحويل إدخال/إخراج الملفات بترميز افتراضي إلى StandardCharsets صريح"
+oldApproach: "الترميز الافتراضي للمنصة"
+modernApproach: "ترميز قياسي صريح"
+summary: "استخدم قارئات وكاتبات Files مع ثوابت StandardCharsets بدلاً من الاعتماد على سلوك الترميز الافتراضي للمنصة والبحث عن اسم الترميز."
+explanation: "تجعل بواني Reader وWriter التي تعتمد على الترميز الافتراضي سلوك الملف يعتمد على بيئة التشغيل. تقبل Files.newBufferedReader() وnewBufferedWriter() ترميزاً صريحاً، بينما توفر StandardCharsets ثوابت مضمونة مثل UTF_8 دون البحث عن سلسلة نصية أو استثناء UnsupportedCharsetException."
+whyModernWins:
+- icon: "🌍"
+  title: "نتائج قابلة للنقل"
+  desc: "تُفكّ نفس البايتات بنفس الطريقة على أي جهاز."
+- icon: "🔒"
+  title: "ثابت معرّف مسبقًا"
+  desc: "لا يمكن أن يحتوي StandardCharsets.UTF_8 على اسم ترميز مكتوب خطأ."
+- icon: "🧩"
+  title: "واجهة ملفات حديثة"
+  desc: "يُعبَّر عن Path والتخزين المؤقت والترميز في عملية واحدة."
+support:
+  description: "متاح على نطاق واسع منذ JDK 7 (يوليو 2011)"

translations/content/bn/io/explicit-charset-file-io.yaml

@@ -0,0 +1,17 @@
+title: "ডিফল্ট চারসেট ফাইল I/O থেকে স্পষ্ট StandardCharsets এ"
+oldApproach: "প্ল্যাটফর্ম ডিফল্ট চারসেট"
+modernApproach: "স্পষ্ট স্ট্যান্ডার্ড চারসেট"
+summary: "প্ল্যাটফর্মের ডিফল্ট চারসেট আচরণ এবং চারসেট-নাম লুকআপের পরিবর্তে StandardCharsets কনস্ট্যান্ট সহ Files রিডার এবং রাইটার ব্যবহার করুন।"
+explanation: "Reader এবং Writer কনস্ট্রাক্টর যা ডিফল্ট চারসেটের উপর নির্ভর করে তা ফাইলের আচরণকে রানটাইম এনভায়রনমেন্টের উপর নির্ভরশীল করে তোলে। Files.newBufferedReader() এবং newBufferedWriter() একটি স্পষ্ট Charset গ্রহণ করে, যেখানে StandardCharsets স্ট্রিং লুকআপ বা UnsupportedCharsetException ছাড়াই UTF_8 এর মতো নিশ্চিত কনস্ট্যান্ট প্রদান করে।"
+whyModernWins:
+- icon: "🌍"
+  title: "পোর্টেবল ফলাফল"
+  desc: "একই বাইট প্রতিটি মেশিনে একইভাবে ডিকোড হয়।"
+- icon: "🔒"
+  title: "পূর্বনির্ধারিত কনস্ট্যান্ট"
+  desc: "StandardCharsets.UTF_8 এ ভুল বানানযুক্ত চারসেট নাম থাকতে পারে না।"
+- icon: "🧩"
+  title: "আধুনিক ফাইল API"
+  desc: "Path, বাফারিং এবং এনকোডিং একটি অপারেশনে প্রকাশ করা হয়।"
+support:
+  description: "JDK 7 (জুলাই 2011) থেকে ব্যাপকভাবে উপলব্ধ"

translations/content/de/io/explicit-charset-file-io.yaml

@@ -0,0 +1,17 @@
+title: "Standard-Charset-Datei-I/O zu explizitem StandardCharsets"
+oldApproach: "Plattformabhängiger Standard-Zeichensatz"
+modernApproach: "Expliziter Standard-Zeichensatz"
+summary: "Verwenden Sie Files-Reader und -Writer mit StandardCharsets-Konstanten statt sich auf das plattformabhängige Standard-Charset-Verhalten und die Zeichensatznamens-Suche zu verlassen."
+explanation: "Reader- und Writer-Konstruktoren, die sich auf den Standard-Zeichensatz verlassen, machen das Dateiverhalten von der Laufzeitumgebung abhängig. Files.newBufferedReader() und newBufferedWriter() akzeptieren ein explizites Charset, während StandardCharsets garantierte Konstanten wie UTF_8 ohne String-Suche oder UnsupportedCharsetException bereitstellt."
+whyModernWins:
+- icon: "🌍"
+  title: "Portable Ergebnisse"
+  desc: "Dieselben Bytes werden auf jeder Maschine identisch dekodiert."
+- icon: "🔒"
+  title: "Vordefinierte Konstante"
+  desc: "StandardCharsets.UTF_8 kann keinen falsch geschriebenen Zeichensatznamen enthalten."
+- icon: "🧩"
+  title: "Moderne Datei-API"
+  desc: "Path, Pufferung und Kodierung werden in einer Operation ausgedrückt."
+support:
+  description: "Seit JDK 7 allgemein verfügbar (Juli 2011)"

translations/content/es/io/explicit-charset-file-io.yaml

@@ -0,0 +1,17 @@
+title: "E/S de archivos con charset por defecto a StandardCharsets explícito"
+oldApproach: "Charset por defecto de la plataforma"
+modernApproach: "Charset estándar explícito"
+summary: "Usa lectores y escritores de Files con constantes de StandardCharsets en lugar de depender del comportamiento del charset por defecto de la plataforma y la búsqueda por nombre de charset."
+explanation: "Los constructores de Reader y Writer que dependen del charset por defecto hacen que el comportamiento del archivo dependa del entorno de ejecución. Files.newBufferedReader() y newBufferedWriter() aceptan un Charset explícito, mientras que StandardCharsets ofrece constantes garantizadas como UTF_8 sin búsqueda por cadena ni UnsupportedCharsetException."
+whyModernWins:
+- icon: "🌍"
+  title: "Resultados portables"
+  desc: "Los mismos bytes se decodifican de forma idéntica en cualquier máquina."
+- icon: "🔒"
+  title: "Constante predefinida"
+  desc: "StandardCharsets.UTF_8 no puede contener un nombre de charset mal escrito."
+- icon: "🧩"
+  title: "API de archivos moderna"
+  desc: "Path, buffering y codificación se expresan en una sola operación."
+support:
+  description: "Ampliamente disponible desde JDK 7 (julio de 2011)"