Java - When do I have to change the serialVersionUID?

Question

I know that I can use serialVersionUID to control the version of classes. And I read that I can then add or remove fields and the class will still be compatible, it will just use default values.

When must I change the serialVersionUID?

Answer 1

The value of the serialVersionUID field is should ideally be changed when incompatible changes are made to the structure of the class. The complete list of incompatible changes is listed in the Java Object Serialization Specification.

To expand further, incompatible changes to a class will prevent the deserialization mechanism from creating an instance of the object, because there is information in the stream that does not map to the current class definition.

Answer 2

If you don't specify a serialVersionUID field in your Serializable classes, the Java compiler will specify one for you -- essentially it's a hash of the fields of the class. Methods can be altered at any time, though, so if you need to change how a stored class is deserialized, you can override the readObject method. If you do specify the serialVersionUID field in your code, though, the compiler won't override that even if you do make incompatible changes, which can result in an exception at runtime -- your IDE or compiler won't give you a warning. (EDIT -- thanks EJB) IDEs such as Eclipse can insert the compiler's UID for you, if you want to easily check how the compiler views certain changes.

If you make changes often, keep an old version of the disk file around to test deserialization with. You can write unit tests to try and read in the old file, and see if it works or if it's totally incompatible.

One caveat, I've personally experienced the pain that is working with Serializable classes originally intended for long-term storage that were improperly designed. For example, storing GUI elements on disk rather than creating them when needed. Ask yourself if Serializable is really the best way to save your data.

Answer 3

I disagree with all this. So does Sun: see this article which they republished on their site.

You should change the serialVersionUID only when you deliberately want to break compatibility with all existing serializations, or when your changes to the class are so radical that you have no choice - in which case you should really think several times about what it is that you are actually doing.

In all other cases you should bust your boiler trying to use custom readObject()/writeObject() and/or writeReplace()/readResolve() methods and/or serialFields annotations so that you can continue to read objects from those existing serializations. Once you break that you are in for a major headache, indeed nightmare.

Answer 4

You can set serialiVersionUID to the same value for the life of the class. (Not always a good idea) Note: you can implement your own serialization version checking strategy with readObject/writeObject if you need this and leave the UID unchanged.

The only time you MUST change it is if you have already serialized some data to a file and you want to read it. If it has changed for any reason you MUST set the serialiVersionUID to the version in the file to have any hope of being able to read the data.