|
|
1687.
|
|
|
Upgrading Applications
|
|
|
type: Content of: <html><body><h1>
|
|
|
|
|
(no translation yet)
|
|
|
|
Located in
howto/upgrading.xhtml:7 howto/upgrading.xhtml:11
|
|
|
1688.
|
|
|
Applications must frequently deal with data that lives longer than the programs that create it. Sometimes the structure of that data changes over time, but new versions of a program must be able to accomodate data created by an older version. These versions may change very quickly, especially during development of new code. Sometimes different versions of the same program are running at the same time, sharing data across a network connection. These situations all result in a need for a way to upgrade data structures.
|
|
|
type: Content of: <html><body><p>
|
|
|
|
|
(no translation yet)
|
|
|
|
Located in
howto/upgrading.xhtml:13
|
|
|
1689.
|
|
|
Basic Persistence: Application and .tap files
|
|
|
type: Content of: <html><body><h2>
|
|
|
|
|
(no translation yet)
|
|
|
|
Located in
howto/upgrading.xhtml:22
|
|
|
1694.
|
|
|
Versioned: New Code Meets Old Data
|
|
|
type: Content of: <html><body><h2>
|
|
|
|
|
(no translation yet)
|
|
|
|
Located in
howto/upgrading.xhtml:53
|
|
|
1695.
|
|
|
So suppose you're running version 1 of some application, and you want to upgrade to version 2. You shut down the program, giving you a .tap file that you could restore with twistd to get back to the same state that you had before. The upgrade process is to then install the new version of the application, and then use twistd to launch the saved .tap file. The old data will be loaded into classes created with the new code, and now you'll have a program running with the new behavior but the old data.
|
|
|
type: Content of: <html><body><p>
|
|
|
|
|
(no translation yet)
|
|
|
|
Located in
howto/upgrading.xhtml:55
|
|
|
1697.
|
|
|
Twisted provides a mechanism called <code class="API" base="twisted.persisted.styles">Versioned</code> to ease these upgrades. Each version of the data structure (i.e. each version of the class) gets a version number. This number must change every time you add or remove a data attribute to the class. It must also change every time you modify one of those data attributes: for example, if you use a string in one version and an integer in another, those versions must have different version numbers.
|
|
|
type: Content of: <html><body><p>
|
|
|
|
|
(no translation yet)
|
|
|
|
Located in
howto/upgrading.xhtml:70
|
|
|
1698.
|
|
|
The version number is defined in a class attribute named <code>persistenceVersion</code>. This is an integer which will be stored in the .tap file along with the rest of the instance state. When the object is unserialized, the saved persistenceVersion is compared against the current class's value, and if they differ, special upgrade methods are called. These methods are named <code>upgradeToVersionNN</code>, and there must be one for each intermediate version. These methods are expected to manipulate the instance's state from the previous version's format into that of the new version.
|
|
|
type: Content of: <html><body><p>
|
|
|
|
|
(no translation yet)
|
|
|
|
Located in
howto/upgrading.xhtml:79
|
|
|
1699.
|
|
|
To use this, simply have your class inherit from <code class="API" base="twisted.persisted.styles">Versioned</code>. You don't have to do this from the very beginning of time: all objects have an implicit version number of <q>0</q> when they don't inherit from Versioned. So when you first make an incompatible data-format change to your class, add Versioned to the inheritance list, and add an <code>upgradeToVersion1</code> method.
|
|
|
type: Content of: <html><body><p>
|
|
|
|
|
(no translation yet)
|
|
|
|
Located in
howto/upgrading.xhtml:89
|
|
|
1700.
|
|
|
For example, suppose the first version of our class saves an integer which measures the size of a line. We release this as version 1.0 of our neat application:
|
|
|
type: Content of: <html><body><p>
|
|
|
|
|
(no translation yet)
|
|
|
|
Located in
howto/upgrading.xhtml:96
|
|
|
1702.
|
|
|
Then we fix some bugs elsewhere, and release versions 1.1 and 1.2 of the application. Later, we decide that we should add some units to the length, so that people can refer to it in inches or meters. Version 1.3 is shipped with the following code:
|
|
|
type: Content of: <html><body><p>
|
|
|
|
|
(no translation yet)
|
|
|
|
Located in
howto/upgrading.xhtml:106
|
