Modify rule S2689: Update rule according to the LayC (#2370)

SonarSource · Jul 3, 2023 · 9e57069 · 9e57069
1 parent fa669b3
commit 9e57069
Show file tree

Hide file tree

Showing 4 changed files with 49 additions and 25 deletions.
diff --git a/rules/S2689/description.adoc b/rules/S2689/description.adoc
diff --git a/rules/S2689/java/rule.adoc b/rules/S2689/java/rule.adoc
@@ -1,25 +1,46 @@
 == Why is this an issue?
 
-include::../description.adoc[]
+An `ObjectOutputStream` writes primitive data types and graphs of Java objects to an `OutputStream`.
+The objects can be read (reconstituted) using an `ObjectInputStream`.
 
+When `ObjectOutputStream` is used with files opened in append mode, it can cause data corruption and unexpected behavior.
+This is because when `ObjectOutputStream` is created, it writes metadata to the output stream, which can conflict with the existing
+metadata when the file is opened in append mode. This can lead to errors and data loss.
 
-=== Noncompliant code example
+When used with serialization, an `ObjectOutputStream` first writes the serialization stream header. This header should appear
+once per file at the beginning.
+When you're trying to read your object(s) back from the file, only the first one will be read successfully, and a `StreamCorruptedException`
+will be thrown after that.
 
-[source,java]
+== How to fix it
+
+Open the file to use the default action (writes stream header).
+
+=== Code examples
+
+==== Noncompliant code example
+
+[source,java,diff-id=1,diff-type=noncompliant]
 ----
-FileOutputStream fos = new FileOutputStream (fileName , true);  // fos opened in append mode
+FileOutputStream fos = new FileOutputStream(fileName , true);  // fos opened in append mode
 ObjectOutputStream out = new ObjectOutputStream(fos);  // Noncompliant
 ----
 
 
-=== Compliant solution
+==== Compliant solution
 
-[source,java]
+[source,java,diff-id=1,diff-type=compliant]
 ----
-FileOutputStream fos = new FileOutputStream (fileName);
+FileOutputStream fos = new FileOutputStream(fileName);
 ObjectOutputStream out = new ObjectOutputStream(fos);
 ----
 
+== Resources
+=== Articles & blog posts
+* https://docs.jboss.org/jbossas/javadoc/4.0.2/org/jboss/util/stream/AppendingObjectOutputStream.java.html[JBoss - AppendingObjectOutputStream]
+
+=== Documentation
+* https://docs.oracle.com/en/java/javase/20/docs/api/java.base/java/io/ObjectOutputStream.html[Oracle SE 20 - ObjectOutputStream]
 
 ifdef::env-github,rspecator-view[]
 

diff --git a/rules/S2689/kotlin/rule.adoc b/rules/S2689/kotlin/rule.adoc
@@ -1,20 +1,35 @@
 == Why is this an issue?
 
-include::../description.adoc[]
+An `ObjectOutputStream` writes primitive data types and graphs of Java objects to an `OutputStream`.
+The objects can be read (reconstituted) using an `ObjectInputStream`.
 
+When `ObjectOutputStream` is used with files opened in append mode, it can cause data corruption and unexpected behavior.
+This is because when `ObjectOutputStream` is created, it writes metadata to the output stream, which can conflict with the existing
+metadata when the file is opened in append mode. This can lead to errors and data loss.
 
-=== Noncompliant code example
+When used with serialization, an `ObjectOutputStream` first writes the serialization stream header. This header should appear
+once per file at the beginning.
+When you're trying to read your object(s) back from the file, only the first one will be read successfully, and a `StreamCorruptedException`
+will be thrown after that.
 
-[source,kotlin]
+== How to fix it
+
+Open the file to use the default action (writes stream header).
+
+=== Code examples
+
+==== Noncompliant code example
+
+[source,kotlin,diff-id=1,diff-type=noncompliant]
 ----
 val fos = FileOutputStream(fileName, true) // fos opened in append mode
 val out = ObjectOutputStream(fos) // Noncompliant
 ----
 
 
-=== Compliant solution
+==== Compliant solution
 
-[source,kotlin]
+[source,kotlin,diff-id=1,diff-type=compliant]
 ----
 val fos = FileOutputStream(fileName)
 val out = ObjectOutputStream(fos)

diff --git a/rules/S2689/metadata.json b/rules/S2689/metadata.json
@@ -1,5 +1,5 @@
 {
-  "title": "Files opened in append mode should not be used with ObjectOutputStream",
+  "title": "Files opened in append mode should not be used with \"ObjectOutputStream\"",
   "type": "BUG",
   "status": "ready",
   "remediation": {
@@ -9,14 +9,6 @@
   "tags": [
     "serialization"
   ],
-  "extra": {
-    "replacementRules": [
-
-    ],
-    "legacyKeys": [
-
-    ]
-  },
   "defaultSeverity": "Blocker",
   "ruleSpecification": "RSPEC-2689",
   "sqKey": "S2689",