Re: [River Wiki] Update of "Serialization" by PeterFirmstone

[Peter Firmstone <ji...@zeus.net.au>]

I've added a page in our wiki for Serialization.

I figure serialization is pretty important for River, so I've added a 
discussion about the Serialization Builder pattern and an example. Feel 
free to add something to it.

Cheers,

Peter.

Apache Wiki wrote:
> Dear Wiki user,
>
> You have subscribed to a wiki page or wiki category on "River Wiki" for change notification.
>
> The "Serialization" page has been changed by PeterFirmstone:
> http://wiki.apache.org/river/Serialization
>
> New page:
> = Serialization Patterns =
> == The Serialization Builder ==
> This pattern is useful for avoiding lock in to serialized form by taking the responsibility for Serialization away from your class and placing it in the hands of a Serialization Buider.
>
> Best used when you have a number of package private classes that implement a common interface or abstract superclass.
>
> When you take the responsibility for serialization away from your class and give it to a builder, the builder becomes responsible for all forms of construction of your class, so your constructors should be package private.
>
> It is of utmost importance that your Builder implementation doesn't become part of your public API and remains package private, to do this you need an abstract superclass with a static method that retrieves your builder implementation.
>
> === The Abstract Builder ===
> {{{
> public abstract class Builder {
>
>     public static Builder new(){
>         return new BuilderImplementation();
>     }
>     
>     public abstract Builder put(Object key, Object value);
>    
>     public abstract Map build();
>
> }
> }}}
> === The Serialization Builder Implementation ===
> {{{
> class SerializationBuilderImp extends Builder implements Serializable {
>
>     private Map mutableMap = new HashMap();
>     
>     public Builder put(Object key, Object value){
>         mutableMap.put(key, value);
>         return this;
>     }
>
>     public Builder putAll(Map map){
>         mutableMap.putAll(map);
>     }
>
>     public Map build(){
>         return new ImmutableMap(mutableMap);
>     }
>
>     private void readObject(ObjectInputStream in)
> 	throws IOException, ClassNotFoundException {
> 	in.defaultReadObject();
>     }
>     
>     private void writeObject(ObjectOutputStream out) throws IOException {
>         out.defaultWriteObject();
>     }
>
>     private Object readResolve(){
>         return build();
>     }
> }
> }}}
> === Package private Map implementation ===
> {{{
> class ImmutableMap extends AbstractMap implements Map, Serializable {
>
>     private final Map immutable;
>     
>     ImmutableMap( Map map ){
>         Map newMap = new HashMap(map.size());
>         newMap.putAll(map);
>         immutable = Collections.unmodifiableMap(newMap);
>     }
>
>     public Set entrySet(){
>         return immutable.entrySet();
>     }
>
>     private Object writeReplace() {
>         // returns a Builder instead of this class.
>         return Builder.new().putAll(immutable);
>     }
>     
>     private void readObject(ObjectInputStream stream) 
>             throws InvalidObjectException{
>         throw new InvalidObjectException("Builder required");
>     }
>     
> }}}
>
>