[math] Does this break the API?

[Sébastien Brisard <se...@m4x.org>]

Dear all,
I'm extremely unfamiliar with serialization and its many pitfalls, and
I would need advice from you wise guys ;-) !!!
Here is the thing. I'm currently working on MATH-761, where for the
sake of "efficiency" (which remains to be asserted [1]), I did some
bad choice on the structure of internal data. I'm willing to clean
this up. The way I see it at the moment, the nested class SymmLQ.State
will probably (probably) go, as it conveys a false sense of security
through encapsulation (not sure I'm very clear, there. In other words:
the code is difficult to read).

This class is private, so the public API would not be broken. However,
there is another nested class, namely SymmLQ.SymmLQEvent which
implements Serializable, and currently holds a reference to an
instance of State. So, I guess that if State disappears in 3.1, events
serialized with 3.0 could not be retrieved with CM v 3.1 (and
vice-versa). Would this be considered as a break of the API?

Sorry if this is a silly question, and thanks in advance for your help!
Best regards,
Sébastien

[1] Thinking about it a few months later, I now realize that my quest
for efficiency was actually completely flawed: I wanted to avoid the
creation of one small object at each iteration, while in the course of
this iteration, a matrix-vector product occurs, with presumably a very
(very) large matrix (since that's what iterative solvers do). So it is
very likely that the iterations are dominated by the product anyway,
unless the matrix is small, in which case a direct solver should be
preferred. Bad, bad, bad... I promise I won't do that again.


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org

Re: [math] Does this break the API?

[Sébastien Brisard <se...@m4x.org>]

Hi Jörg,
thanks for this detailed answer.

2012/3/9 Jörg Schaible <Jo...@scalaris.com>:
> Hi Sébastian,
>
> Sébastien Brisard wrote:
>
>> Dear all,
>> I'm extremely unfamiliar with serialization and its many pitfalls, and
>> I would need advice from you wise guys ;-) !!!
>> Here is the thing. I'm currently working on MATH-761, where for the
>> sake of "efficiency" (which remains to be asserted [1]), I did some
>> bad choice on the structure of internal data. I'm willing to clean
>> this up. The way I see it at the moment, the nested class SymmLQ.State
>> will probably (probably) go, as it conveys a false sense of security
>> through encapsulation (not sure I'm very clear, there. In other words:
>> the code is difficult to read).
>>
>> This class is private, so the public API would not be broken. However,
>> there is another nested class, namely SymmLQ.SymmLQEvent which
>> implements Serializable, and currently holds a reference to an
>> instance of State. So, I guess that if State disappears in 3.1, events
>> serialized with 3.0 could not be retrieved with CM v 3.1 (and
>> vice-versa). Would this be considered as a break of the API?
>>
>> Sorry if this is a silly question, and thanks in advance for your help!
>> Best regards,
>> Sébastien
>>
>> [1] Thinking about it a few months later, I now realize that my quest
>> for efficiency was actually completely flawed: I wanted to avoid the
>> creation of one small object at each iteration, while in the course of
>> this iteration, a matrix-vector product occurs, with presumably a very
>> (very) large matrix (since that's what iterative solvers do). So it is
>> very likely that the iterations are dominated by the product anyway,
>> unless the matrix is small, in which case a direct solver should be
>> preferred. Bad, bad, bad... I promise I won't do that again.
>
> In principal, yes, it breaks binary compatibility.
>
That's what I was afraid of...

> However, you can
> implement it in a binary compatible way. Note, that every time you modify
> the binary class layout, you also have to change the serialVersionUID
> (that's the reason why I take normally a value that reflects the date,
> today's choice would be 20120309L).
>
Yes, I forgot to mention that I would at the very least change this
uid. We actually agreed a few months ago to use this date convention
in CM as well (maybe it was you who suggested it in the first place, I
can't remember!).

>
> How to verify compatibility: Write a .ser file with the old version, add it
> in the head revision to src/test/data and write a new unit test that can
> load it as well as new ones. Look at the JDK docs how to write serialization
> functions to ensure compatibility. It might be necessary to keep State
> around for the time being although it is no longer used.
>
> commons-id has some test code that ensures that the binary class layout of a
> serializable object has not been changed.
>
It's good to know there is a way to do things properly, so I'll make
sure I look into that. However, following Luc's answer, maybe I'll
take the liberty *not* to follow these rules, if the implications are
too restrictive.
Thanks again for taking the time to answer this in detail, I'll make
good use of this answer!

Sébastien
> Cheers,
> Jörg
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org

Re: [math] Does this break the API?

[Jörg Schaible <Jo...@scalaris.com>]

Hi Sébastian,

Sébastien Brisard wrote:

> Dear all,
> I'm extremely unfamiliar with serialization and its many pitfalls, and
> I would need advice from you wise guys ;-) !!!
> Here is the thing. I'm currently working on MATH-761, where for the
> sake of "efficiency" (which remains to be asserted [1]), I did some
> bad choice on the structure of internal data. I'm willing to clean
> this up. The way I see it at the moment, the nested class SymmLQ.State
> will probably (probably) go, as it conveys a false sense of security
> through encapsulation (not sure I'm very clear, there. In other words:
> the code is difficult to read).
> 
> This class is private, so the public API would not be broken. However,
> there is another nested class, namely SymmLQ.SymmLQEvent which
> implements Serializable, and currently holds a reference to an
> instance of State. So, I guess that if State disappears in 3.1, events
> serialized with 3.0 could not be retrieved with CM v 3.1 (and
> vice-versa). Would this be considered as a break of the API?
> 
> Sorry if this is a silly question, and thanks in advance for your help!
> Best regards,
> Sébastien
> 
> [1] Thinking about it a few months later, I now realize that my quest
> for efficiency was actually completely flawed: I wanted to avoid the
> creation of one small object at each iteration, while in the course of
> this iteration, a matrix-vector product occurs, with presumably a very
> (very) large matrix (since that's what iterative solvers do). So it is
> very likely that the iterations are dominated by the product anyway,
> unless the matrix is small, in which case a direct solver should be
> preferred. Bad, bad, bad... I promise I won't do that again.

In principal, yes, it breaks binary compatibility. However, you can 
implement it in a binary compatible way. Note, that every time you modify 
the binary class layout, you also have to change the serialVersionUID 
(that's the reason why I take normally a value that reflects the date, 
today's choice would be 20120309L).

How to verify compatibility: Write a .ser file with the old version, add it 
in the head revision to src/test/data and write a new unit test that can 
load it as well as new ones. Look at the JDK docs how to write serialization 
functions to ensure compatibility. It might be necessary to keep State 
around for the time being although it is no longer used.

commons-id has some test code that ensures that the binary class layout of a 
serializable object has not been changed.

Cheers,
Jörg


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org

Re: [math] Does this break the API?

[Luc Maisonobe <Lu...@free.fr>]

Le 09/03/2012 08:14, Sébastien Brisard a écrit :
> Dear all,

Hi Sébastien,

> I'm extremely unfamiliar with serialization and its many pitfalls, and
> I would need advice from you wise guys ;-) !!!
> Here is the thing. I'm currently working on MATH-761, where for the
> sake of "efficiency" (which remains to be asserted [1]), I did some
> bad choice on the structure of internal data. I'm willing to clean
> this up. The way I see it at the moment, the nested class SymmLQ.State
> will probably (probably) go, as it conveys a false sense of security
> through encapsulation (not sure I'm very clear, there. In other words:
> the code is difficult to read).
> 
> This class is private, so the public API would not be broken. However,
> there is another nested class, namely SymmLQ.SymmLQEvent which
> implements Serializable, and currently holds a reference to an
> instance of State. So, I guess that if State disappears in 3.1, events
> serialized with 3.0 could not be retrieved with CM v 3.1 (and
> vice-versa). Would this be considered as a break of the API?

I don't think so.
As decided on this list, we almost don't support serialization. In the
few places where it is supported, we should not guaranteed any
cross-version compatibility.

best regards,
Luc

> 
> Sorry if this is a silly question, and thanks in advance for your help!
> Best regards,
> Sébastien
> 
> [1] Thinking about it a few months later, I now realize that my quest
> for efficiency was actually completely flawed: I wanted to avoid the
> creation of one small object at each iteration, while in the course of
> this iteration, a matrix-vector product occurs, with presumably a very
> (very) large matrix (since that's what iterative solvers do). So it is
> very likely that the iterations are dominated by the product anyway,
> unless the matrix is small, in which case a direct solver should be
> preferred. Bad, bad, bad... I promise I won't do that again.
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org