From fd53e6ccabd0f338ba4903e7d988455478ac9460 Mon Sep 17 00:00:00 2001 From: eiffel-org Date: Fri, 26 May 2017 12:14:01 +0000 Subject: [PATCH] Update wikipage Persistence, storage, and retrieval. (Signed-off-by:b-meyer). git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@1831 abb3cda0-5349-4a8f-a601-0c33ac3a8c38 --- .../Persistence--storage--and-retrieval.wiki | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/documentation/17.01/solutions/basic-computing/eiffelbase/eiffelbase-tutorial/eiffelbase-kernel/Persistence--storage--and-retrieval.wiki b/documentation/17.01/solutions/basic-computing/eiffelbase/eiffelbase-tutorial/eiffelbase-kernel/Persistence--storage--and-retrieval.wiki index 50884a82..6af02155 100644 --- a/documentation/17.01/solutions/basic-computing/eiffelbase/eiffelbase-tutorial/eiffelbase-kernel/Persistence--storage--and-retrieval.wiki +++ b/documentation/17.01/solutions/basic-computing/eiffelbase/eiffelbase-tutorial/eiffelbase-kernel/Persistence--storage--and-retrieval.wiki @@ -13,13 +13,15 @@ A fundamental requirement on object persistence mechanisms is the ''Persistence Storing an object just by itself would usually result in wrong semantics: most objects contain references to other objects, which must also be stored and retrieved with it. The persistence completeness rule ensures that this is always the case. It also means, of course, that features used for storing and retrieving objects must do much more than simple input and output; they must perform complete traversals of object structures. +The Eiffel persistence mechanism applies Persistence Completeness. + =Varieties of store operations= Different variants of the store operation are available: '''session''', '''basic''' and '''independent''' store * '''Session''' store produces the most compact structure in the resulting files; but the resulting structure is dependent on the current execution of the system which executes the store operation (''System'' is taken here, as elsewhere in this documentation, in its Eiffel sense of an executable assembly of classes, compiled together with the help of a configuration file.) -* '''Basic''' store is like session store with the difference that the resulting structure is dependent on the system which executes the store operation (i.e. only the system creating the storable can retrieve it.) +* '''Basic''' store is like session store with the difference that the resulting structure is dependent on the system which executes the store operation (i.e. only the system creating the persistent version can retrieve it.) * On the other hand, '''independent''' store allows a system running on a computer with a certain architecture to retrieve, without any explicit conversion operation, object structures stored by a system running on a machine of a completely different architecture. In addition, independent store lets you retrieve an old version of the object that was saved (see more details in the recoverable section below.) @@ -27,17 +29,17 @@ Different variants of the store operation are available: '''session''', '''basic Historically, the persistence mechanism was offered via the helper class [[ref:libraries/base/reference/storable_chart|STORABLE]] which you could use as an ancestor whenever you wanted to store and retrieve objects. Via this class you would have access to basic_store and independent_store to store an object, and retrieved to retrieve one. However this was not necessary and the persistence mechanism could be used directly from any descendants of the [[ref:libraries/base/reference/io_medium_chart|IO_MEDIUM]] using routines with the same names. This manner of storing and retrieving objects is called the '''C''' persistence mechanism since it was completely written in C and is included as part of the Eiffel runtime. -Today, we recommend using the '''SED''' ('''SE'''rialization '''D'''eserialization) persistence mechanism, entirely written in Eiffel. It is very flexible as it lets you control the format of storables but most users will use its helper class [[ref:libraries/base/reference/sed_storable_facilities_chart|SED_STORABLE_FACILITIES]]. This class offers session_store, basic_store, and store (the de-facto independent store), as well as retrieved. +Today, we recommend using the '''SED''' ('''SE'''rialization '''D'''eserialization) persistence mechanism, entirely written in Eiffel. It is very flexible, sinceit lets you control the format of the stored structure, but in most cases it suffices to rely on the simple helper class [[ref:libraries/base/reference/sed_storable_facilities_chart|SED_STORABLE_FACILITIES]]. This class offers session_store, basic_store, and store (the de-facto independent store), as well as retrieved. In both cases, you only need to be aware of the difference between the various storing mechanism (session, basic and independent) at storage time. The stored structure will always be available through feature retrieved; this feature will figure out, from the format of the stored structure how it was stored and will decode it accordingly. -{{Caution|This is only true when using just the '''C''' storable or the '''SED''' storable. If it was stored using the '''C''' storable, you need to use the '''C''' retrieved feature. Conversely, if it was stored using '''SED''', you need to use the '''SED''' retrieval mechanism.}} +{{Caution|This is only true when using just the '''C''' or '''SED''' persistence format. If the structure was stored using the '''C''' format, you need to use the '''C''' retrieved feature. Conversely, if it was stored using '''SED''', you need to use the '''SED''' retrieval mechanism.}} Regardless of the mechanism used, the feature retrieved returns a result of type [[ref:libraries/base/reference/any_chart|detachable ANY]] and is typically used through an object test. -==With C storable== +==With the C persistence format== -The example below will show you how to store an object using the C storable mechanism. It uses independent_store but you could also use in-place basic_store instead: +The example below will show you how to store an object using the C persistence format. It uses independent_store but you could also use in-place basic_store instead: store_object (o: ANY; p: PATH) @@ -75,9 +77,9 @@ retrieve (p: PATH) If the structure in the file has been corrupted and retrieved is unable to do its job, it will trigger an exception (the code for that exception in class [[ref:libraries/base/reference/exceptions_chart|EXCEPTIONS]] (which inherits it from EXCEP_CONST and is discussed in the next section, together with the notion of exception code) is Retrieve_exception.) -==With SED storable== +==With the SED persistence format== -The example below will show you how to store an object using the SED storable mechanism assuming the current class is a descendant of [[ref:libraries/base/reference/sed_storable_facilities_chart|SED_STORABLE_FACILITIES]]. It uses the store feature but you could also use session_store or basic_store too. +The example below will show you how to store an object using the SED mechanism assuming the current class is a descendant of [[ref:libraries/base/reference/sed_storable_facilities_chart|SED_STORABLE_FACILITIES]]. It uses the store feature but you could also use session_store or basic_store too. store_object (o: ANY; p: PATH) @@ -119,7 +121,7 @@ retrieve (p: PATH) In case of an error during retrieval, no objects will be returned and instead the query retrieved_errors will list all the errors it encountered. -=Recoverable storable= +=Recoverable format= Sometimes you will be in a position where the schema of a class will have changed between the time you stored your object and the time you are trying to retrieve it. Such changes include: * class name changed @@ -127,7 +129,7 @@ Sometimes you will be in a position where the schema of a class will have change * attributes have been renamed * attributes type have been changed -The storable mechanism allows you to retrieve the old version of the object only if it was saved using the independent_store facility. Each time you retrieve an object of a certain base class whose schema has changed, the feature correct_mismatch will be called. This feature is defined in [[ref:libraries/base/reference/any_chart|ANY]] and by default will raise an exception. To handle the mismatch, you need to redefine correct_mismatch in the base class whose schema has been changed. For example in EiffelBase, [[ref:libraries/base/reference/hash_table_chart|HASH_TABLE]] has changed between version 5.1 and version 5.2 to use SPECIAL rather than [[ref:libraries/base/reference/array_chart|ARRAY]] for its internal data storage. To retrieve a 5.1 version of [[ref:libraries/base/reference/hash_table_chart|HASH_TABLE]], you need to define correct_mismatch as following: +The persistence mechanism allows you to retrieve the old version of the object only if it was saved using the independent_store facility. Each time you retrieve an object of a certain base class whose schema has changed, the feature correct_mismatch will be called. This feature is defined in [[ref:libraries/base/reference/any_chart|ANY]] and by default will raise an exception. To handle the mismatch, you need to redefine correct_mismatch in the base class whose schema has been changed. For example in EiffelBase, [[ref:libraries/base/reference/hash_table_chart|HASH_TABLE]] has changed between version 5.1 and version 5.2 to use SPECIAL rather than [[ref:libraries/base/reference/array_chart|ARRAY]] for its internal data storage. To retrieve a 5.1 version of [[ref:libraries/base/reference/hash_table_chart|HASH_TABLE]], you need to define correct_mismatch as following: correct_mismatch -- Attempt to correct object mismatch during retrieve using `mismatch_information'.