The persistence interfaces

Persist

The GNOME::Persist-interface inherits directly from GNOME::Unknown and serves as a base class for the other Persist*-classes. It supports the following method:

   interface Persist : Unknown {
      enum Status {
        SAVE_OK,
        SAVE_CANCEL,
        SAVE_FAILED
      };
      string get_goad_id ();
      exception WrongDataType {};
    };

• get_goad_id Gets the GOAD id for the datatype.

PersistFile

The PersistFile-interface specifically addresses the need to write and save to files (rather than stream and storages). As such, the main application of this interface is to for (embedded) components store/retrieve their state in/for separate files.

interface PersistFile : Persist {

    exception NoCurrentName {
        string extension;
    };

    void load (in string path) raises (WrongDataType);
    void save (in string path);
    boolean is_dirty ();
    string get_current_file () raises (NoCurrentName);
};

• load: Loads a component's persistent state from a file on the given path. load raises a 'WrongDataType' when the persistent state is not valid for this type of component.

• save: Saves a component's state to a file on the given path.

• is_dirty Returns whether the internal component's state has changed from its persistent (file) state.

• get_current_file Returns the name of the file we're using for the persistence of this component. Raises a NoCurrentName if there's not such a file yet.

PersistStorage

Embedded components supporting the PersistStorage-interface enable their container to pass them a storage object (as described in the previous chapter). The PersistStorage-interface addresses embedded components that are containers themselves, and therefore need a storage (rather than a stream) to store their state.

The main application of this interface is to support persistence for contained objects that are containers themselves.

interface PersistStorage : Persist {
    boolean is_dirty ();
    void load (in Storage storage) raises (WrongDataType);
    void save (in Storage storage, in boolean same_as_loaded);
    void init_new (in Storage storage);
};

• load: Loads a component's persistent state from a storage. load raises a 'WrongDataType' when the persistent state is not valid for this type of component.

• save: Saves a component's state to the given storage. Function also needs a same_as_loaded boolean parameter, denoting we're doing a 'save' or a 'save-as' operation.

• is_dirty: Returns true if the internal component's state has changed, from its persistent (file) state, and false otherwise.

• init_new: Initializes the given storage.

PersistStream

Embedded components supporting the PersistStream-interface enable their container to pass them a stream object (as described in the previous chapter). The PersistStream-interface addresses embedded components that are non-aggregates and can thus be stored in a stream.

interface PersistStream : Persist {
    boolean is_dirty ();
    void load (in Stream stream) raises (WrongDataType);
    void save (in Stream stream);
    long get_size_max ();
};

• is_dirty: Returns true if the internal component's state has changed, from its persistent state, and false otherwise.

• load: Loads a component's persistent state from a stream. load raises a 'WrongDataType' when the persistent state is not valid for this type of component.

• save: Saves a component's state to the given stream.

• get_size_max: Returns the size (in bytes) of the stream needed to save the component's state.