Implementing persistence for a custom feature renderer

• About persistence
• Persistence in extension classes
• Persistence behavior implementation
• Version compatibility
• Version compatibility implementation
• Points to remember

About persistence

• In a map collection, each map persists the ArcObjects corresponding to its layers, symbology, graphics, current extent, spatial reference, and so on. This can also include custom layers, renderers, symbols, elements, or other map items.
• Page layout, map frames, map surrounds, and layout of items can also include custom map surrounds or frames.
• Visible table of contents (TOC) views can also include a custom TOC view.
• Visible toolbars, their members and position (if floating) can include standard and custom toolbars, and commands and UIControls.
• List of styles referenced by the StyleGallery and items stored in a style by using persistence, can include a custom StyleGalleryItem or StyleGalleryClass. 

Persistence in extension classes

Persistence behavior implementation

• The custom feature renderer extension class implements the java.io.Externalizable interface to support persistence.
• The dispersalRatio property of the PointDispersalRenderer is identified as its persisted property, which is of the Java double primitive type. 
• The Externalizable.writeExternal() method implementation persists the dispersalRatio property to the stream.
• The Externalizable.readExternal() method implementation retrieves the dispersalRatio property. When the map document opens, the custom feature renderer object is rehydrated by retrieving the stored properties and the framework renders the layer appropriately.

@ArcGISExtension public class PointDispersalRenderer implements IFeatureRenderer,
    java.io.Externalizable{

    double dispersalRatio;

    //Write the variables.
    public void writeExternal(ObjectOutput out)throws IOException{
        //Write the dispersal ratio value to persistent storage to preserve the state.
        out.writeDouble(this.dispersalRatio);
    }

    //Read the variables. 
    public void readExternal(ObjectInput in)throws IOException,
        ClassNotFoundException{
        //Read the dispersal ratio from the persistent storage and rehydrate the object.
        this.dispersalRatio = in.readDouble();
    }
}

Version compatibility

Version compatibility implementation

• When an  extension instance that implements IDocumentVersionSupportGen is persisted to the stream, the ArcGIS framework invokes the IDocumentVersionSupportGen.isSupportedAtVersion() method to determine the ArcGIS document versions supported by the extension.
• If isSupportedAtVersion returns true, ArcGIS appropriately handles the persistence behavior of the extension.
• If isSupportedAtVersion returns false, ArcGIS calls the IDocumentVersionSupportGEN.convertToSupportedObject method. The method returns an alternative object that can be persisted to the specified ArcGIS document version, which is persisted instead of the extension instance. See the following illustration that shows this scenario:
  
  

@ArcGISExtension 
//Notice, the PointDispersalRenderer class implements IDocumentVersionSupportGen.
public class PointDispersalRenderer implements IFeatureRenderer,
    java.io.Externalizable, IDocumentVersionSupportGEN{
    //The method returns the alternative renderer if the version is not equal to ArcGIS 9.3.
    public Object convertToSupportedObject(int arg0)throws IOException,
        AutomationException{
        SimpleRenderer simpleRend = new SimpleRenderer();
        SimpleMarkerSymbol simpleMarkerSymbol = new SimpleMarkerSymbol();
        simpleMarkerSymbol.setSize(8);
        simpleMarkerSymbol.setStyle(esriSimpleMarkerStyle.esriSMSDiamond);
        simpleRend.setSymbolByRef(simpleMarkerSymbol);
        return simpleRend;

    }

    //The method verifies the supported versions.
    public boolean isSupportedAtVersion(int docVersion)throws IOException,
        AutomationException{
        /***********
        //The esriArcGISVersion enumeration does not specify an enum value for ArcGIS 9.3.1. 
        //Therefore, the code example allows persisting custom ArcObjects to ArcGIS 9.3 documents.
        // However, when opening the map document in ArcGIS 9.3, the layer will not be rendered.  
        //Therefore, it is the developer's responsibility to ensure 
        //ArcGIS 9.3.1 is installed to open map documents saved to ArcGIS 9.3.
         ****************/
        //Support all versions above or equal to ArcGIS 9.3.
        if (docVersion >= esriArcGISVersion.esriArcGISVersion93)
            return true;
        else
        //The convertToSupportedObject() method will be invoked if isSupportedAtVersion() returns false.
            return false;
    }