Changes between Version 1 and Version 2 of TracDev/PluginDevelopment/ExtensionPoints/trac.env.IEnvironmentSetupParticipant

Timestamp:

May 12, 2010, 8:23:28 PM (14 years ago)

Author:

Carsten Klein <carsten.klein@…>

Comment:

Finalized the initial version of the documentation for the IEnvironmentSetupParticipant extension point interface.

TracDev/PluginDevelopment/ExtensionPoints/trac.env.IEnvironmentSetupParticipant

@@ -4 +4 @@
 ||'''Module'''||''trac.env''||'''Source'''||[source:trunk/trac/env.py#L51 env.py]||
 
-The ''IEnvironmentSetupParticipant'' is responsible for either creating a new environment or to upgrade (aka migrate) an existing environment to a newer version of the database. In addition to that, the implementation of the extension point interface might also migrate existing data in the database so that it will correspond to the newly installed changes to the existing database schema, or similar such use cases.
+The ''IEnvironmentSetupParticipant'' is responsible for either creating a new environment or to upgrade (aka migrate) an existing environment to a newer version of that environment.
 
-The implementation will be called on either ''trac-admin <env-dir> initenv'' or, if an existing environment must be upgraded, on ''trac-admin <env-dir> upgrade''.
+Implementations of the extension point interface will be called during both ''trac-admin <env-dir> initenv'' and on ''trac-admin <env-dir> upgrade''.
 
 == Purpose ==
 
-TBD
+Responsibilities of the interface are to participate in the creation of a new environment. This includes adding information to the database schema, such as table declarations and so on. Some implementations, see below, might also opt in for adding default data to the newly created database, or to set up the folder where the environment will be created in.
 
-Provide detailed information on the purpose of the interface here. E.g. ''IAuthenticator'' is used by the main request dispatcher to associate the current request's session with a user, or, in case that no such user exists, with the anonymous user. The most basic implementation would search for a cookie in the request. Other, more elaborated implementations for example would provide single sign on for example by evaluating an existing request header, and so on.
+On environment upgrade, the responsibilities of the participant are to non-destructively migrate existing user data to a newer database schema, provided that the data model has changed at the SQL level, and of course to migrate the environment's folder structure and content to meet the requirements of the participant.
 
 == Usage ==
 
-Provide detailed usage information of the extension point and implementations thereof. E.g. when is a method of the implementation being called and so on.
-
+Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
 
 == Examples ==
 
-Provide one or more example implementations of the interface.
+The following example basically does nothing more than logging to the standard log file during either ''trac-admin <env-dir> initenv'' or ''trac-admin <env-dir> upgrade''.
+
+{{{#!python
+from trac.core import implements, Component
+
+class SampleEnvironmentSetupParticipant(Component):
+
+    implements(IEnvironmentSetupParticipant)
+
+    # IEnvironmentSetupParticipant methods
+
+    def environment_created():
+        self.log.debug("creating environment for sample plugin.")
+        pass
+
+    def environment_needs_upgrade(db):
+        self.log.debug("the existing environment requires an upgrade for sample plugin.")
+        return True
+
+    def upgrade_environment(db):
+        self.log.debug("upgrading existing environment for sample plugin.")
+        pass
+}}}
 
 == Available Implementations ==
 
-Provide references to available implementations of the interface, for example by linking to sources in trac trunk or on trac-hacks. You might also include short discussions on how they have been implemented.
+ * [source:trunk/trac/env.py#L558 trac.env.EnvironmentSetup][[br]]
+   This is the setup participant that will initialize the trac database and also the sample configuration provided with each trac instance, providing sane initial defaults for use with both an existing environment and a newly created one. For the creation of a new environment it uses [source:trunk/trac/db_default.py the default db structure]. and on upgrade it will use [source:trunk/trac/upgrades a db upgrade path] defined in the individual db*.py modules therein. The version number of the trac database schema is available from the ''system'' table, the key to look for is ''database_version.'' The value of this system property will be updated on environment upgrade. In addition to that, trac will also keep track of the initial database version that was installed when first creating the environment. The key to look for in the ''system'' table is ''initial_database_version''.
+