Java - ObjectOutputStream useProtocolVersion(int version) method

---

---

Description

The Java ObjectOutputStream useProtocolVersion(int version) method specifies stream protocol version to use when writing the stream.

This routine provides a hook to enable the current version of Serialization to write in a format that is backwards compatible to a previous version of the stream format.

• It sets the serialization protocol version used by ObjectOutputStream.

• It must be called before writing any data.

• Only two valid values −

  • ObjectStreamConstants.PROTOCOL_VERSION_1 → old JDK 1.1 format (no class descriptors)

  • ObjectStreamConstants.PROTOCOL_VERSION_2 → modern format (default since JDK 1.2)

• It throws IOException if called after data has been written.

Declaration

Following is the declaration for java.io.ObjectOutputStream.useProtocolVersion(int version) method.

public void useProtocolVersion(int version)

Parameters

version − use ProtocolVersion from java.io.ObjectStreamConstants.

Return Value

This method does not return a value.

Exception

• IllegalStateException − If called after any objects have been serialized.

• IllegalArgumentException − If invalid version is passed in.

• IOException − If I/O errors occur.

Example - Usage of ObjectOutputStream useProtocolVersion(int version) method

The following example shows the usage of ObjectOutputStream useProtocolVersion(int version) method.

ObjectOutputStreamDemo.java

package com.tutorialspoint;

import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.ObjectInputStream;
import java.io.ObjectOutputStream;
import java.io.ObjectStreamConstants;

public class ObjectOutputStreamDemo {
   public static void main(String[] args) {
      Object s = "Hello World!";
      Object s2 = "Bye World!";
      
      try {
         // create a new file with an ObjectOutputStream
         FileOutputStream out = new FileOutputStream("test.txt");
         ObjectOutputStream oout = new ObjectOutputStream(out);

         // change protocol version
         oout.useProtocolVersion(ObjectStreamConstants.PROTOCOL_VERSION_1);

         // write something in the file
         oout.writeObject(s);
         oout.writeObject(s2);

         // close the stream
         oout.close();

         // create an ObjectInputStream for the file we created before
         ObjectInputStream ois = new ObjectInputStream(new FileInputStream("test.txt"));

         // read and print a string
         System.out.println("" + (String) ois.readObject());
         System.out.println("" + (String) ois.readObject());
      } catch (Exception ex) {
         ex.printStackTrace();
      }
   }
}

Output

Let us compile and run the above program, this will produce the following result −

Hello World!
Bye World!

Example - Switch to legacy protocol version (PROTOCOL_VERSION_1)

The following example shows the usage of ObjectOutputStream useProtocolVersion(int version) method. We're doing a forced serialization to use the older version 1 protocol.

ObjectOutputStreamDemo.java

package com.tutorialspoint;

import java.io.FileOutputStream;
import java.io.IOException;
import java.io.ObjectOutputStream;
import java.io.ObjectStreamConstants;
import java.io.OutputStream;

public class ObjectOutputStreamDemo {
   public static void main(String[] args) throws IOException {
      try (LegacyOOS oos = new LegacyOOS(new FileOutputStream("legacy.ser"))) {
         oos.writeObject("Legacy format string");
      }
   }

   static class LegacyOOS extends ObjectOutputStream {
      public LegacyOOS(OutputStream out) throws IOException {
         super(out);
         useProtocolVersion(ObjectStreamConstants.PROTOCOL_VERSION_1);
         System.out.println("Switched to PROTOCOL_VERSION_1");
      }
   }
}

Output

Let us compile and run the above program, this will produce the following result−

Switched to PROTOCOL_VERSION_1

Explanation

• By calling useProtocolVersion(PROTOCOL_VERSION_1), we tell Java to serialize using the old-school format (no full class descriptors).

• Useful for compatibility with older systems or custom deserializers.

Example - Use default modern protocol and log it

The following example shows the usage of ObjectOutputStream useProtocolVersion(int version) method. We're explicitly using the default modern protocol (version 2) and confirm via log.

ObjectOutputStreamDemo.java

package com.tutorialspoint;

import java.io.FileOutputStream;
import java.io.IOException;
import java.io.ObjectOutputStream;
import java.io.ObjectStreamConstants;
import java.io.OutputStream;

public class ObjectOutputStreamDemo {
   public static void main(String[] args) throws IOException {
      try (ModernOOS oos = new ModernOOS(new FileOutputStream("modern.ser"))) {
         oos.writeObject("Modern format string");
      }
   }

   static class ModernOOS extends ObjectOutputStream {
      public ModernOOS(OutputStream out) throws IOException {
         super(out);
         useProtocolVersion(ObjectStreamConstants.PROTOCOL_VERSION_2);
         System.out.println("Using PROTOCOL_VERSION_2 (default)");
      }
   }
}

Output

Let us compile and run the above program, this will produce the following result−

Using PROTOCOL_VERSION_2 (default)

Explanation

• Even though version 2 is the default, this shows you how to explicitly set it (useful in configurable serializers).

• You might pair this with getProtocolVersion() if you're building a version-aware tool.