Merge remote-tracking branch 'origin/main' into brunoborges-websocket-client-pattern

# Conflicts:
#	content/io/http-client.yaml
#	content/io/io-class-console-io.yaml

Author: brunoborges

content/collections/legacy-synchronized-collections.yaml

@@ -0,0 +1,48 @@
+---
+id: d54a4e9f-74b9-4579-84a3-2541fe7b4272
+slug: "legacy-synchronized-collections"
+title: "Legacy synchronized collections to modern alternatives"
+category: "collections"
+difficulty: "intermediate"
+jdkVersion: "5"
+oldLabel: "Legacy synchronized collection"
+modernLabel: "Concurrent Collections API"
+oldApproach: "Hashtable"
+modernApproach: "ConcurrentHashMap"
+oldCode: |-
+  Hashtable<String, Session> sessions = new Hashtable<>();
+  sessions.put(id, session);
+modernCode: |-
+  ConcurrentMap<String, Session> sessions = new ConcurrentHashMap<>();
+  sessions.put(id, session);
+summary: "Replace Vector and Hashtable with collections selected for actual mutability and concurrency needs."
+explanation: "Vector and Hashtable synchronize every operation through legacy APIs. Modern\
+  \ code should normally use ArrayList or HashMap for thread-confined data, and purpose-built\
+  \ concurrent collections when shared mutation is required."
+whyModernWins:
+- icon: "🎯"
+  title: "Intentional concurrency"
+  desc: "The chosen type documents whether sharing is expected."
+- icon: "⚡"
+  title: "Better scalability"
+  desc: "ConcurrentHashMap avoids a single table-wide lock for normal access."
+- icon: "🧩"
+  title: "Modern APIs"
+  desc: "Works naturally with current collection and concurrent-map operations."
+support:
+  state: "available"
+  description: "Widely available since JDK 5 (September 2004)"
+prev: "collections/unmodifiable-collectors"
+next: "strings/string-isblank"
+related:
+- "collections/immutable-map-creation"
+- "collections/copying-collections-immutably"
+- "concurrency/lock-free-lazy-init"
+tags:
+- collections
+- concurrency
+docs:
+- title: "ConcurrentHashMap"
+  href: "https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/concurrent/ConcurrentHashMap.html"
+- title: "ConcurrentMap"
+  href: "https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/concurrent/ConcurrentMap.html"

content/collections/stack-to-deque.yaml

@@ -0,0 +1,49 @@
+---
+id: 5ec6dc04-e96e-4d30-a11c-ea48c9d28fbf
+slug: "stack-to-deque"
+title: "Stack to Deque and ArrayDeque"
+category: "collections"
+difficulty: "beginner"
+jdkVersion: "6"
+oldLabel: "Legacy Stack"
+modernLabel: "Deque API"
+oldApproach: "Stack"
+modernApproach: "Deque with ArrayDeque"
+oldCode: |-
+  Stack<String> stack = new Stack<>();
+  stack.push("task");
+  String next = stack.pop();
+modernCode: |-
+  Deque<String> stack = new ArrayDeque<>();
+  stack.push("task");
+  String next = stack.pop();
+summary: "Use the Deque interface with ArrayDeque instead of the legacy Stack class."
+explanation: "Stack extends the legacy synchronized Vector class. Deque models stack operations directly, and ArrayDeque is the preferred general-purpose implementation for in-memory LIFO work."
+whyModernWins:
+- icon: "🎯"
+  title: "Better abstraction"
+  desc: "Deque explicitly models both stack and queue operations."
+- icon: "⚡"
+  title: "Lower overhead"
+  desc: "ArrayDeque avoids Vector's legacy synchronization."
+- icon: "🧩"
+  title: "More flexible"
+  desc: "The same interface supports LIFO and FIFO algorithms."
+support:
+  state: "available"
+  description: "Available since JDK 6 (December 2006)"
+prev: "enterprise/spring-boot-mvc-config"
+next: null
+related:
+- "collections/sequenced-collections"
+- "collections/reverse-list-iteration"
+- "collections/immutable-list-creation"
+tags:
+- collections
+docs:
+- title: "Deque (Java 25)"
+  href: "https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Deque.html"
+- title: "ArrayDeque (Java 25)"
+  href: "https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/ArrayDeque.html"
+- title: "Stack (Java 25)"
+  href: "https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Stack.html"

content/collections/unmodifiable-collectors.yaml

@@ -36,7 +36,7 @@ support:
   state: "available"
   description: "Widely available since JDK 16 (March 2021)"
 prev: "collections/reverse-list-iteration"
-next: "strings/string-isblank"
+next: "collections/legacy-synchronized-collections"
 related:
 - "collections/immutable-map-creation"
 - "collections/immutable-set-creation"

content/datetime/hex-format.yaml

@@ -41,7 +41,7 @@ support:
   state: "available"
   description: "Widely available since JDK 17 LTS (Sept 2021)"
 prev: "datetime/math-clamp"
-next: "security/pem-encoding"
+next: "datetime/locale-of"
 related:
 - "datetime/date-formatting"
 - "datetime/instant-precision"

content/datetime/locale-of.yaml

@@ -0,0 +1,45 @@
+---
+id: 361b53ba-ec9d-45a1-95e5-8c4b3aa7731a
+slug: "locale-of"
+title: "Locale constructors to Locale.of()"
+category: "datetime"
+difficulty: "beginner"
+jdkVersion: "19"
+oldLabel: "Deprecated constructor"
+modernLabel: "Java 19+"
+oldApproach: "Locale constructors"
+modernApproach: "Locale.of()"
+oldCode: |-
+  Locale brazilianPortuguese =
+      new Locale("pt", "BR");
+modernCode: |-
+  Locale brazilianPortuguese =
+      Locale.of("pt", "BR");
+summary: "Create language and region locales with Locale.of() instead of deprecated constructors."
+explanation: "Locale factory methods replace constructors deprecated in JDK 19. The factory\
+  \ form is clearer, aligns with other value-based APIs, and centralizes locale creation."
+whyModernWins:
+- icon: "✅"
+  title: "Supported API"
+  desc: "Avoids deprecated constructors."
+- icon: "👁"
+  title: "Clear construction"
+  desc: "The named factory communicates intent."
+- icon: "🧩"
+  title: "Consistent style"
+  desc: "Matches modern JDK value-object factories."
+support:
+  state: "available"
+  description: "Available since JDK 19 (September 2022)"
+prev: "datetime/hex-format"
+next: "security/pem-encoding"
+related:
+- "datetime/date-formatting"
+- "datetime/java-time-basics"
+- "strings/string-formatted"
+tags:
+- datetime
+- constructors
+docs:
+- title: "Locale.of()"
+  href: "https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Locale.html#of(java.lang.String,java.lang.String)"

content/enterprise/spring-boot-mvc-config.yaml

@@ -44,7 +44,7 @@ support:
   state: "available"
   description: "Available in Spring Boot 4.0 with Spring Framework 7.0 (requires Java 17+)"
 prev: "enterprise/spring-null-safety-jspecify"
-next: null
+next: "collections/stack-to-deque"
 related:
 - "enterprise/spring-api-versioning"
 - "enterprise/spring-xml-config-vs-annotations"

content/io/http-websocket-client.yaml

@@ -49,7 +49,7 @@ support:
   state: "available"
   description: "Widely available since JDK 11 (September 2018)"
 prev: "io/http-client"
-next: "io/io-class-console-io"
+next: "io/url-constructors-to-uri"
 related:
 - "io/http-client"
 - "concurrency/completablefuture-chaining"

content/io/io-class-console-io.yaml

@@ -43,7 +43,7 @@ whyModernWins:
 support:
   state: "available"
   description: "Finalized in JDK 25 alongside compact source files (JEP 512)"
-prev: "io/http-websocket-client"
+prev: "io/url-constructors-to-uri"
 next: "io/reading-files"
 related:
 - "language/compact-source-files"

content/io/url-constructors-to-uri.yaml

@@ -0,0 +1,52 @@
+---
+id: d0e90aba-b424-4b96-b0cc-471f6141d71a
+slug: "url-constructors-to-uri"
+title: "Deprecated URL constructors to URI"
+category: "io"
+difficulty: "intermediate"
+jdkVersion: "20"
+oldLabel: "Deprecated URL constructor"
+modernLabel: "Java 20+"
+oldApproach: "Direct URL construction"
+modernApproach: "URI then URL"
+oldCode: |-
+  URL endpoint =
+      new URL("https://example.com/api?q=java");
+modernCode: |-
+  URI endpointUri =
+      URI.create("https://example.com/api?q=java");
+  URL endpoint = endpointUri.toURL();
+summary: "Parse and compose resource identifiers as URI values before converting to URL\
+  \ when necessary."
+explanation: "URL constructors were deprecated in JDK 20 because URL parsing and equality\
+  \ have surprising protocol-handler behavior. URI is the preferred immutable representation\
+  \ for parsing, composition, comparison, and normalization; convert only at APIs that\
+  \ require URL."
+whyModernWins:
+- icon: "✅"
+  title: "Avoids deprecation"
+  desc: "Removes use of deprecated URL constructors."
+- icon: "🧠"
+  title: "Predictable semantics"
+  desc: "URI comparison does not perform network-dependent resolution."
+- icon: "🧩"
+  title: "Better composition"
+  desc: "URI is designed for parsing and manipulating identifiers."
+support:
+  state: "available"
+  description: "URL constructors deprecated since JDK 20 (March 2023)"
+prev: "io/http-websocket-client"
+next: "io/io-class-console-io"
+related:
+- "io/http-client"
+- "io/path-of"
+- "io/reading-files"
+tags:
+- io
+- http
+- migration
+docs:
+- title: "URI"
+  href: "https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/net/URI.html"
+- title: "URL"
+  href: "https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/net/URL.html"

content/security/pem-encoding.yaml

@@ -39,7 +39,7 @@ whyModernWins:
 support:
   state: "preview"
   description: "Preview in JDK 25 (JEP 470). Requires --enable-preview."
-prev: "datetime/hex-format"
+prev: "datetime/locale-of"
 next: "security/key-derivation-functions"
 related:
 - "security/key-derivation-functions"